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Preface 


This manual describes how to develop a program that uses 
the Advanced Program-to-Program Communication for the 
IBM Personal Computer (APPC/PC) program product. 
APPC/PC is a data communication system that enables 
IBM PC transaction programs to communicate with other 
transaction programs on other IBM PCs that have 
APPC/PC. APPC/PC also enables the IBM PC to 
communicate with APPC on other systems, such as the 
Series/1, System/36, System/38, and System/370 CICS. 


APPC/PC provides programs with a distributed 
transaction processing capability. APPC/PC enables a 
program on an IBM PC to communicate with another 
program on another system without operator intervention. 
This manual shows you how to write IBM PC transaction 
programs that use APPC/PC to communicate with other 
programs. 


Who Should Use This Manual 


Application programmers can use this manual to develop 
programs that use the APPC/PC application program 
interface (API). The API consists of the commands (verbs) 
and return codes described in this manual. The 
application programmer needs to know how to program 
the IBM PC, and needs to understand SNA concepts. 


How This Manual is Organized 


Chapter 1, “Introduction to APPC/PC,” describes 
supported features of APPC/PC and how APPC/PC fits in 
the IBM PC relative to other IBM PC programs. It 
describes transaction programs and application subsystem 
programs and introduces other terms used throughout this 
manual. 
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Chapter 2, “Developing an Application Subsystem,” 
describes functions that should be considered when 
designing an application subsystem. 


Chapter 3, “Developing a Transaction Program,” 
describes functions that should be considered when 
designing a transaction program. 


Chapter 4, “Introduction to APPC/PC Verbs,” briefly 
describes verb types and the common verb format used in 
chapters 5 through 9. 


Chapter 5, “Using Control Verbs,” describes the 
application program interface (API) to control verbs. 
First, the control verbs that the application subsystem 
sends to APPC/PC are described, followed by the control 
verbs APPC/PC sends to the application subsystem. Near 
the end of this chapter there are examples of activating 
and deactivating a node. 


Chapter 6, “Using Transaction Mapped Conversation 
Verbs,” describes the application program interface for 
mapped conversation verbs. Preceding the individual verb 
descriptions is a discussion of the conversation states that 
determine which verbs can be issued, and a discussion on 
understanding mapped conversation return codes. 


Chapter 7, “Using Transaction Basic Conversation 
Verbs,” describes the application program interface for 
basic conversation verbs. Preceding the individual verb 
descriptions is a discussion of the conversation states that 
determine which verbs can be issued, and a discussion on 
understanding basic conversation return codes. 


Chapter 8, “Using the Network Management Verb,” 
describes the verb used to provide management services 
information to a network management services function. 


Chapter 9, “Other APPC/PC Services,” describes other 
verbs provided by APPC/PC for the convenience of the 
programmer. One verb assists with communication 
between the application subsystem and transaction 
programs. Other verbs assist with data conversion 


(ASCII/EBCDIC), tracing facilities, and disabling and 
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reenabling APPC/PC to avoid recursion problems in exit 
routines. 


Chapter 10, “Resolving Error Conditions,” describes three 
types of error conditions with possible solutions and ways 
to avoid them. The types of errors discussed are return 
codes, SYSLOG reported errors, and system deadlocks. 


Appendix A, “Verb Operation Codes and Formats,” lists 
the operation codes for APPC/PC verbs and the internal 
formats for the parameter lists passed between the 
application subsystem or the transaction program, and 


APPC/PC. 


Appendix B, “Conversation State Matrices,” shows the 
conversation state transitions that can occur when a 
program issues a conversation verb. 


Appendix C, “Verb Return Codes,” shows the return 
codes that APPC/PC can report to a program through the 
RETURN_CODE parameter of each verb. 


Appendix D, “SYSLOG Type Codes,” lists the SYSLOG 
type codes that represent error conditions and includes 
data errors reported by the transaction program, link 

errors, configuration errors, and system protocol errors. 


Appendix E, “Sample Programs,” describes the sample 
programs supplied on the APPC/PC Structures and 
Sample Programs diskette. There is also a listing for a 
sample CICS program. 


Appendix F, “Sample CICS Host Configuration for 
APPC/PC,” describes sample CICS and VTAM definitions 
necessary to use APPC/PC. 


Appendix G, “APPC/PC. Implementation of the LU6.2 
Architecture,” describes the optional functions of APPC 
architecture supported by APPC/PC. This appendix also 
includes a mapping of APPC/PC verbs and parameters 
with the verbs and parameters used in the APPC 
architecture documents. 


Appendix H, “ASCII/EBCDIC Translation Tables,” 
describes translation tables used by the conversion verb 
provided by APPC/PC. 


Appendix I, “Statement of Service,” contains a discussion 
of IBM service as related to the APPC/PC program 
product. 


Following the appendices are a glossary and an index. 


Related Publications 


The following publications provide additional information 
on the topics discussed in this manual. 
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Advanced Program-to-Program Communication for the 
IBM Personal Computer Installation and Configuration 
Guide contains planning and IBM PC set-up 
information for APPC/PC. 


Introduction to Advanced Program-to-Program 
Communication, GG24-1584, contains general 
information about APPC. 


Systems Network Architecture Concepts and Products, 
GC30-3072, contains basic information on SNA for 
those readers wanting either an overview or a 
foundation for further study. 


Systems Network Architecture Technical Overview, 
GC30-3073, contains additional details on SNA, 
especially on functions and control sequences; bridges 
the gap between the most elementary overview of SNA 
and the detailed descriptions of the formats and 
protocols. 


Systems Network Architecture Transaction 
Programmer's Reference Manual for LU Type 6.2, 
GC30-3084, contains reference information on LU type 


6.2 (APPC) verbs for programmers writing transaction 
programs to run on SNA. 


Systems Network Architecture Format and Protocol 
Reference Manual: Architecture Logic for LU Type 6.2, 
SC30-3269, contains information for system 
programmers and others who need detailed information 
about SNA LU Type 6.2 (APPC) to adapt a program to 
function within an SNA network. 


Systems Network Architecture Sessions Between Logical 
Units, GC20-1868, contains references on SNA formats 
and protocols for LU types other than Type 6.2. 


Systems Network Architecture Reference Summary, 
GA27-3136, contains summary information on SNA 
formats and sequences. 


IBM SDLC General Information, GA27-3093, contains 
supplementary details of Synchronous Data Link 
Control. 


IBM Token-Ring Network Introduction and Planning 
Guide, GA27-3677, contains planning information for 
IBM Token-Ring Network. 


IBM Token-Ring Network PC Adapter Guide to 
Operations, SA27-3710, is the IBM Token-Ring Network 
operations guide. 


IBM Token-Ring Network PC Adapter Technical 
Reference Manual, SC30-3383, contains additional 
reference information for IBM Token-Ring Network. 


IBM Token-Ring Network Problem Determination 
Guide, SY27-1280, contains information on problem 
diagnosis for the IBM Token-Ring Network. 


IBM Option Instructions for the SDLC Communication 
Adapter, supplied with the IBM SLDC communication 
adapter, contains adapter installation and connector 
information. 


vii 


vill 


Contents 


Chapter 1. Introduction to APPC/PC ......... 1-1 
The APPC/PC Program ................005. 1-1 
What You Need ........... 0... ee eee ee ee 1-2 
Features Supported ........... 200.0 e eae 1-3 
SNA and APPC Terminology ................ 1-4 
APPC/PC for the Transaction Programmer ..... 1-6 

Understanding Locally Initiated and Remotely 
Initiated Transactions .................. 1-7 
Supporting Multiple Conversations ........ 1-7 
APPC/PC for the System Programmer ......... 1-7 
Understanding Initial Application Subsystem to 
APPC/PC Interactions ................. 1-9 
Managing Incoming Requests for 
CONVERSATIONS 0405s. ask 44 Be Saved Acero eS 1-9 


Chapter 2. Developing an Application Subsystem 2-1 


Coding the Initial Attach Sequence ........... 2-2, 
Starting a Transaction Program ............. 2-3 
Supporting Multiple Transaction Programs ..... 2-7 
Using Application Subsystem Exits ........... 2-9 
Canceling a Transaction ..............008. 2-13 
DOS: Mitermpts: wey. oa edhe ed dk Me BSA ee dos 2-14 
Chapter 3. Developing a Transaction Program . 3-1 
Understanding Application Protocols ......... 3-1 
Understanding the Conversation States ........ 3-2 


Understanding the Available APPC/PC Services . 3-3 
Choosing Between Basic and Mapped 


CONVerSatIONS: 64.4 S654 seo Se Gears oS ee vw eh 3-6 
Understanding the Conversation Type ...... 3-7 
mending Data 2 excised to hae w ates Soe pow 3-8 
RECEIVING Data. = s416 dine Wei ape de een 3-9 
Reporting Errors and Abnormal Termination 3-10 
Sending an Error Log Data Record ........ 3-11 
Abnormally Terminating Because of a 

PAMC Ob 55 ete Ke dik oh wa Se bese Sess es 3-11 
Requesting Confirmation ................-. 3-12 


1x 


Choosing a Transaction Program Name ....... 3-12 


Using the Network Management Verb ........ 3-13 
Using the Security Features ............... 3-13 
Partner-LU Verification (Session-Level 
DOCUPICY): 2 eet ar Oo ous yee gen tase Fae 3-13 
End-User Verification (Conversation-Level 
DOCULILY © AGU ais ae ee Oe aoe eR eas 3-14 
Converting between EBCDIC and ASCII ...... 3-15 
Chapter 4. Introduction to APPC/PC Verbs .... 4-1 
VED: EY POS: to ese ccatw Soe ede Sea Se eae Sea 4-1 
Control: Verbs) s.0--gaso- ki we ee pa eee 4-1 
Mapped Conversation Verbs .............. 4-2, 
Basic Conversation Verbs ................ 4-2 
Network Management Verb .............. 4-2 
Other Verbs? 6s blue ee bee Wik Poe aes 4-3 
Verb Descriptions ........... 2.0. cee eee ens 4-3 
General Description ..............00 eee 4-4 
Supplied Parameters .......... 0.000 e eee 4.4 
Returned Parameters ...........0000 0 eee 4-5 
Chapter 5. Using Control Verbs ............. 5-1 
Understanding Control Verb Return Codes ..... 5-3 
Application Subsystem to APPC/PC ........... 5-5 
ACTIVATE! DLO. aic3.64.5 520844 50h eee eee 5-5 
PTAC SN: sty hats eee. 6 he ee ale eee eG 5-7 
ALIACHA PO fied on tan dara te wees 5-17 
CHANGE LW <244-ic8 BA teased ee wee 5-20 
CNOS (Change Number of Sessions) ....... 5-23 
DETACH. EW wagaoss Pe sah dgae wet dada « 5-45 
BEPACH SPU utc eccsds auxieh ee ee ads 5-47 
DISPAY 255, 3502 4-6 haha tek aa aoa we 5-50 
GET: ALLOCATE: | facaawasmk Fok eee ta 5-54 
Ps SHUNTED: 6 tn deg ch- gta te thane eae ele aca eee 5-56 
PEO PAR DED: 22h Seed a aud ewe ae 5-58 
TR = VARIG sale totic ke Raeaed cand Cae e Genee 4 5-60 
APPC/PC to Application Subsystem .......... 5-62 
ACCESS: UU GU LPW  i4 hcacee ca eice Sea 5-63 
CRATE PS in doa coh cet a.e aida aren ea Beka 5-66 
OO ioe iio di ama ge ae RN ae eee B 5-72 
Activating and Deactivating a Node ......... 5-75 
Activating a Node <4... .646.4248 05 6520465 5-75 
Deactivating a Node ................... 5-77 


Chapter 6. Using Transaction Mapped 


Conversation Verbs ..........eccecceeees 


Understanding Mapped Conversation States 
Understanding Mapped Conversation Return 


COGCSS . iri le eda See ha 2) Geer eth eked ee tack 


Verb Descriptions ............ 2.0. eee eee 
MC_ALLOCATE ............. Ae ee 
NEC  CONPURM. . a3: den axa ness ate oe ae eS 
MC_CONFIRMED .................... 
MC_DEALLOCATE ............000000- 
MC! PRUSE 2.244 ces -O Ssh te dae ais 
MC_GET ATTRIBUTES ............... 
GH. JEY PE exten ent deeds os a CA 
MC_PREPARE TO_RECEIVE .......... 
MC_RECEIVE_AND_ WAIT ............ 
MC_RECEIVE_IMMEDIATE ........... 
MC_REQUEST_TO_SEND ............. 
MC_SEND_DATA .................... 
MC_SEND_ERROR ................... 
WEG TS itp a5eabte 2a ace hae a 


Chapter 7. Using Transaction Basic 


Conversation Verbs ......... ccc cece eee 
Understanding Basic Conversation States ...... 


Understanding Basic Conversation Return Codes 
Verb Descriptions ............ 02. 
ALLOCATE: tn a5 So's thane ao Aeb a are8 ho Oates 
CONFIRM. 2 0:24 segs aes yw haces Oe ee 
CONPEIR MEAD . « scghete & oto aocukee eas oes an 
DEALLOCA TE co cst iwi 6 8 eee a 
PN selec he ree a A hawt wl We cea ared tech he ean ee has 
GET_ATTRIBUTES ................... 
GE eV 6 salar ath srannatenl ntact She tale Nails 
POSTON. -RECHIPT 935.4 shade da bale 
PREPARE TO RECEIVE .............. 
RECEIVE_AND_ WAIT ................ 
RECEIVE IMMEDIATE ............... 
REQUEST_TO_ SEND ................. 
SUNDA LA. is cx aera eh atid ones eee 
SEND “ERROR. - 25:5 905. «ce he aa eis ae w es 
PSE Serica tat tal toh aed oeh ee aha ae betb ties 


XI 


Chapter 8. Using the Network Management Verb 8-1 


Understanding the Network Management Verb .. 8-1 
yd Co) oo ame a ee a a eNO 8-2 
Problem Determination Statistics .......... 8-2 

Nerb Description: cia divs seh eee ee CRE ORS 8-3 
TRANSFER MS DATA ................ 8-3 

Chapter 9. Other APPC/PC Services ......... 9-1 

Verb Descriptions ........ 0... eee eee eee 9-2 
SET _PASSTHROUGH .................. 9-2 
PASSTHROUGH ............ 2.020 e eee 9-3 
COIN Y Re yiisetec fee Se rls, 8 Ste: a nendin Sok loaded taal ee 9-4 
PRAT sich dod e nes wa tas Gara teal Ovaree 68 Gee er tnee eee ee 9-8 
DISABLE/ENABLE_APPC ............. 9-12 

Chapter 10. Resolving Error Conditions ...... 10-1 

Return Code Error Indications .............. 10-1 

Logged Brrots: 2.66 ii gk eb See Se ewes 10-2 

System Deadlocks ............. 000 eee aes 10-2 
Using Multiple Active Transaction Programs 10-2 
Designing to Avoid System Deadlocks ..... 10-5 
Investigating a Deadlock Situation ........ 10-7 

Appendix A. Verb Operation Codes and Formats A-1 

APPC/PC to Transaction Program Verbs ...... A-1 

Transaction Program to APPC/PC Verbs ...... A-2 

Verb Operation Codes ............0.00000. A-3 

Verb Record Formats .............00 cee aee A-4 
ACCESS_LU_LU_PW ................. A-6 
ACTIVATE DGC. o:2 >. cc lectus eas wees A-6 
ALLOCATE and MC ALLOCATE ........ A-7 
ATTACH. JG 263.2302 en 6h bo eC ES oe Sees A-8 
ATEPACH PW: 230%. 05 k-cm otek a ee aetie aSealend A-10 
CHANGE: GU? geacineu dae Mate ea fated. oan A-11 
CNOS* sctaui hones Gage tates es examen A-11 
CONFIRM or MC_CONFIRM ........... A-18 
CONFIRMED or MC_CONFIRMED ...... A-14 
CONV IR i yte-eg. cg ee Be dee ee aes A-14 
CREATE. UP ato ba geed Megs tensed Saeed A-15 
DEALLOCATE or MC_DEALLOCATE .... A-16 
DETACH GU nese casas t ne aan eh tae es A-17 
DETACH 2PUs tra% tor dinn Saw Matern bok SS A-18 


XU 


DISABLE/ENABLE_APPC ............. A-18 


DISPEAY, 46 oi hee i on ee A-18 
FLUSH or MC_FLUSH ................ A-19 
GET ALLOCATE 5.2.06: c500¢ een eee: A-20 
GET_ATTRIBUTES or 
MC_GET_ATTRIBUTES .............. A-20 
GET TYPE ............ 000 ccc eeeeee A-21 
PASSTHROUGH .............000-000- A-29 
POST ON_RECEIPT ................-- A-29 
PREPARE _TO_RECEIVE and 
MC_PREPARE_TO RECEIVE ......... A-23 
RECEIVE_AND_ WAIT and 
MC_RECEIVE_AND WAIT ........... A-24 
RECEIVE_IMMEDIATE and 
MC_RECEIVE_IMMEDIATE .......... A-25 
REQUEST _TO_SEND and 
MC_REQUEST_TO_ SEND ............ A-27 
SEND DATA or MC_SEND_DATA ...... A-27 
SEND_ERROR or MC_SEND ERROR .... A-28 
SET PASSTHROUGH ................. A-30 
SYSLOG ...cccc cede veseneeveceeves A-30 
TEST or MC_TEST .............. 0000. A-30 
TP -BNDEDccueevniiaaeaeiwd ene eceee A-32 
TP_STARTED .............. 000 eee eee A-32 
TP V ALD 3c tsu tee olen on i om Boece A-33 
TP RBCE race ehoua a ook keene A-33 
TRANSFER MS DATA ............... A-35 
WA acura, a saree ok tiie se a dettae east o Paea, te A-36 


Appendix B. Conversation State Matrices .... B-1 


Appendix C. Verb Return Codes ........... C-1 
Common Return Codes .............20200005% C-2 
Verb-Specific Return Codes ................ C-14 

Appendix D. SYSLOG Type Codes .......... D-1 
IBM Token-Ring Network Problems ......... D-5 

Link-Level Errors ..................00.4- D-5 
Network Management NMVT Messages .... D-9 
PORTS: os. oun hack od b-2 Sian ond Ade ae ee D-10 
SDGG Provlems.. atscxérite a od Kat GRR S D-22 
30-millisecond CTS Dropout ............. D-23 
30-millisecond DSR Dropout ............. D-23 


X1il 


40-second Transmit Failure .............. D-23 


5-second DISC Not Received Time-out ..... D-23 
10-second Inactivity Time-out ............ D-23 
Appendix E. Sample Programs ............ E-1 
Sample Conversation ............00 cee wane E-4 
Sample Program Execution ..............200. E-5 
Modifying the Sample Program for SDLC ...... E-7 
APPC/PC—CICS Sample Program ............ E-8 
Appendix F. Sample CICS Host Configuration 
TOV APPC/ PC: s56:2 ose Bele Oe wee oe Geek F-1 
Appendix G. APPC/PC Implementation of the 
LUG.2 Archit@cture. < s-6 66064 dB es Se ee G-1 
Base and Option Sets for APPC/PC .......... G-1 
Basic Conversation Verbs ...............4- G-2 
Mapped Conversation Verbs ............... G-8 
ContrOl!V ens = sod-os oe ea eee e ys task Bae G-14 
Network Management Verb ................ G-16 
Other APPC/PC Services .................. G-16 


Appendix H. ASCII/EBCDIC Translation Tables H-1 


Appendix I. Statement of Service ........... I-1 
GIOSSATY) <n6-2445 45 Gb ORE EH bee Pe ew oe X-1 
TINGS og doe Bhs Nes aid ate ana Re ae ae X-17 


X1V 


Chapter 1. Introduction to 
APPC/PC 


The APPC/PC Program 


APPC/PC is a data communications subsystem for the 
IBM Personal Computer. APPC/PC provides SNA 
Advanced Program-to-Program Communication (APPC) 
for application programs that perform distributed 
transaction processing. 


An application program using APPC/PC can communicate 
with application programs on other systems that support 
APPC. In this book a transaction program is an 
application program that uses APPC/PC communication 
functions. 


Transaction programs use APPC/PC verb sequences to 
communicate with other programs at other SNA nodes. 
You can regard this set of verbs as a programming 
language in which you can write conversations. 
APPC/PC verbs are coded as records, each having a 
precisely defined syntax. Your transaction programs gain 
access to APPC/PC facilities by providing verb records to 
the APPC/PC application program interface (API) that 
appears as an operating system extension of PC DOS. 


Whether you write your own application or use an 
existing application, you must first set up your IBM 
Personal Computer to operate in a computer network. 
APPC/PC simplifies setup by providing configuration 
menus that help you configure your IBM Personal 
Computer for connection to an IBM Token-Ring Network, 
to an SNA data communication network using 
Synchronous Data Link Control (SDLC) leased or 
switched facilities, or to both. A simple direct connection 
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between IBM Personal Computers using SDLC is also 
possible. 


What You Need 


To 
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use APPC/PC as described in this manual, you need: 


The APPC/PC program product consisting of the 
APPC/PC Installation and Configuration Guide and 
two diskettes: the APPC/PC Program Diskette, and 
the APPC/PC Structures and Sample Programs 
diskette. 


The Guide describes hardware and software 
requirements and provides information on planning, 
configuring, and loading APPC/PC. 

The APPC/PC Program Diskette contains: 

— APPC/PC load and unload commands 

— The APPC/PC configuration program 

— Data Link Control files 


— A sample type G conversation table. 


The APPC/PC Structures and Sample Programs 
diskette contains: 


— APPC/PC assembler verb structures, which are 
used to write application subsystems and 
transaction programs 


— A set of sample programs to illustrate the design of 


an application subsystem and the coding of 
APPC/PC verbs using the macro assembler verb 
structures. 


e In addition to the APPC/PC program product, you 
need a language to compile your application subsystem 
and transaction programs. You can use any language 
that supports: 

— Issuing software interrupts 


— Setting general registers 


— Building parameter lists (as described in Appendix 
A) 


— Providing addressability to sections of code. 
For information on specifying the APPC/PC configuration 


and running APPC/PC, see the APPC/PC Installation and 
Configuration Guide. 


Features Supported 


APPC/PC provides the SNA APPC node support as 
defined in the SNA Format and Protocol Reference 
Manual. 

APPC/PC supports an open API including the following: 
e Base APPC (LU Type 6.2/PU Type 2.1) 


e Parallel sessions (when attached to peer PU Type 2.1 
nodes) 


e Synchronization level of None or Confirm 
e Mapped conversation support (but no data mapping) 
e Peer and boundary function attachment 


e Support for conversation- and session-level security 
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e Network Management support for ALERT, PDSTATS, 
and general NMVTs 


e Normal Response Mode SDLC 
— Primary point-to-point 
— Secondary point-to-point or multipoint 


— Switched support for manual dial, manual answer, 
and auto-answer 


e IBM Token-Ring Network support 
e Compatibility with CICS/VS Version 1.7 


e Operation under the latest level of IBM PC DOS at 
availability of the IBM Token-Ring Network. 


SNA and APPC Terminology 


The diagram below illustrates the relationship between 
the IBM PC hardware and the software components 
involved in the operation of APPC/PC. 


Application Subsystem 


Composite 
SNA 


Operating Node 
System 
(PC-DOS) 
ROM BIOS 
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The application subsystem refers to one or more programs 
whose primary function is to provide services for 
APPC/PC and transaction programs. The application 
subsystem logs errors, manages incoming conversations, 
loads transaction programs, and provides other services. 
The transaction programs use APPC/PC communication 
services to communicate with a partner transaction 
program to perform transactions. The API is the set of 
commands that the application subsystem and transaction 
programs use to communicate with APPC/PC. The 
application subsystem and transaction programs are 
provided by the user. 


A remote transaction program can request a local 
application subsystem to start a local transaction program 
so that the programs can exchange data. The 
corresponding transaction programs are called partner 
transaction programs. 


You can choose the type of conversation that your 
transaction program uses: a basic conversation or a 
mapped conversation. The type of conversation you use 
depends on whether you need full access to the SNA 
general data stream (GDS) as provided by basic 
conversations. A header field (LLID) precedes all data 
that a program sends in the GDS format. The logical 
length (LL) portion of the header field specifies the 
overall length of the data and the identification (ID) 
portion specifies the type of data. 


In basic conversations, data passed to and received from 
the APPC/PC API must contain at least the LL fields of 
the GDS headers. (See SNA Reference Summary for 
information on GDS variables.) The transaction program 
must build and interpret the LL fields but the ID fields are 
optional. The ID information is necessary only if the 
partner program expects to receive GDS variables. 


In mapped conversations, the data that programs pass to 
and receive from the APPC/PC API is simply user data. A 
transaction program using mapped conversations does not 
require GDS headers to describe the data; therefore, the 
program does not have to build or interpret these headers. 
When the transaction program uses mapped 
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conversations, APPC/PC builds and interprets GDS 
variables. 


APPC/PC verbs fall into three general categories: 


e Conversation verbs used by a transaction program to 
communicate data 


e Control verbs that an application subsystem uses to 
request services from or provide services to APPC/PC 


e System services verbs for tasks such as network 
management and ASCII/EBCDIC conversion. 


APPC/PC for the Transaction 
Programmer 


APPC/PC provides a transaction program API and an 
interface to the control functions within the application 
subsystem that the system programmer provides. 


The communication services of APPC/PC extend the 
services that the operating system normally provides. 
These services include communication primitives that 
enable a transaction to use a conversation to 
communicate with a partner transaction. Each 
conversation is half-duplex—that is, the transaction 
program with the right to send data must give up that 
right before its partner transaction program can send 
data. For descriptions of the capabilities of the 
transaction API, see Chapter 6, “Using Transaction 
Mapped Conversation Verbs,” and Chapter 7, “Using 
Transaction Basic Conversation Verbs.” 
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Understanding Locally Initiated and 
Remotely Initiated Transactions 


A transaction can start in one of two ways: by an action 
initiated at your IBM PC or by an action initiated by a 
remote transaction program. Initially, the creating 
transaction program has the right to send data and the 
created transaction program does not have the right to 
send data. After initialization, the verb sequences that 
the programs issue determine the right to send data. 


Supporting Multiple Conversations 


A transaction program can have conversations with 
several partners simultaneously. However, a transaction 
that a remote program initiates is always a new 
transaction. Therefore, to have more than one 
conversation with remote programs, a local program must 
initiate all conversations except the first one. 


Each conversation uses a logical resource called a session, 
and the conversation can use this session for as long as it 
requires. However, while a conversation is using a 
session, no other conversation can use it. Whena 
transaction requests APPC/PC to allocate a conversation, 
APPC/PC responds by establishing a conversation and 
assigning it to a session. 


APPC/PC for the System 
Programmer 


The system programmer provides an application subsystem 
that uses the defined APPC/PC interface. The primary 
function of the application subsystem is to provide 
services for APPC/PC, but the system programmer can 
also use the application subsystem to provide services for 
the transaction programs. 


1-7 


The application subsystem manages the services of the 
communication node not managed by APPC/PC. These 
services include: 


e Defining the logical characteristics of the node, 
including the Physical Unit (PU), the Logical Units 
(LUs), the partner LUs, and the desired number of 
sessions with each partner 


e Activating the adapters 
e Handling logged error messages 


e Providing LU-LU passwords (if security features are 
required) 


e Validating and loading a remotely initiated 
transaction program (if the capability for remote 
initiation is required) 


e Managing cancellation of a transaction program 
(optional). 


In addition to the application subsystem services just 
listed, the system programmer can provide other services 
to the transaction program, as appropriate. 


The interface between the application subsystem and 
APPC/PC consists of two parts: 


e A verb interface to establish the PU and the LUs, and 
to define partner LUs, session limits, and other 
communication parameters. Control verbs are 
described in Chapter 5, “Using Control Verbs.” 


e A set of exit routines to manage incoming transaction 
requests, log errors, and provide LU-LU passwords, 
also described in Chapter 5, “Using Control Verbs.” 


For information on the design of an application subsystem 
see Chapter 2, “Developing an Application Subsystem.” 
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Understanding Initial Application 
Subsystem to APPC/PC Interactions 


The application subsystem must issue verbs to define the 
capabilities of the communication node. An 
ATTACH PU verb establishes the PU and an 
ATTACH_LU verb establishes each LU. These verbs 
provide information such as the LU name, processing 
capabilities, and a method of handling incoming requests 
for conversations. The application subsystem issues verbs 
so that the transaction programmer does not need to be 
concerned with the system definition. 


For example, the system programmer may want to provide, 
as part of the application subsystem, predefined utility 
routines to execute attachment sequences for particular 
system configurations. 


Managing Incoming Requests for 
Conversations 


The application subsystem must manage requests for 
conversations (incoming ALLOCATEs) from other 
transaction programs. The system programmer must 
decide, for each LU, the best way to manage these 
incoming ALLOCATKs. Three options are available: 


e The application subsystem can reject incoming 
ALLOCATEs entirely 


e The application subsystem can provide an exit 
procedure that APPC/PC can call when an incoming 
ALLOCATE arrives (asynchronous option). 


e You can direct the LU to queue the incoming 
ALLOCATESs until the application subsystem requests 
them (synchronous option) 


To process an incoming ALLOCATE, the application 


subsystem must validate the request, load and/or initiate 
the requested transaction program, and provide the 
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transaction program with the parameters it must have to 
issue APPC/PC conversation verbs. 
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Chapter 2. Developing an 
Application Subsystem 


APPC/PC runs under an application subsystem that 
manages features such as node definition, incoming 
requests for conversations (incoming ALLOCATEs), and 
error logging. This chapter describes the APPC/PC 
support options available to the application subsystem 
designer. 


Efficient designs separate the application subsystem from 
the transaction programs, and define and manage nodes 
separately from the transaction programs so that these 
transaction programs can concentrate on conversations 
with particular partners. In this way you need to define 
the characteristics of the node and its partners only once, 
independently of the individual conversations. 


Certain portions of the application subsystem should be 
loaded and remain resident during transaction processing, 
so that they can communicate with the transaction 
programs as necessary. These portions become a DOS 
extension, just as APPC/PC becomes a DOS extension. An 
example of how to create an application subsystem is 
described in Appendix E, “Sample Programs.” 
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Coding the Initial Attach 
Sequence 


After loading APPC/PC through a DOS command, the 
normal sequence for the application subsystem to issue 
APPC/PC verbs is as follows: 


The ATTACH_PU verb defines and establishes APPC/PC 
conversations for the PU. It must be the first verb issued 
after APPC/PC loading, or, if the node is to be redefined, 

the first verb issued after issuing DETACH PU. 


The ATTACH LU verb defines each local LU and its 
characteristics, the potential partner LUs, and the 
transmission service modes (called modes). It specifies 
session limits for the LU, the partner LU, and the mode. 
The ATTACH LU verb returns an identifier of the LU 
(LU_ID). The application subsystem must save the 
LU_ID so that it can be used to specify the LU to which 
the transaction belongs. 


The ACTIVATE _ DLC verb opens the adapters 
designated in the APPC/PC menus. The application 
subsystem should issue this verb after issuing the 
ATTACH_LU verb. This sequence avoids receiving 
messages from a remote node before the application 
subsystem defines the local LU. 


If you are using a switched SDLC link, you should make 
the connection at this point. 


The CNOS verb sets the active number of sessions with a 
partner LU, and negotiates session limits with a partner 
LU if parallel sessions are defined. The application 
subsystem should issue the CNOS verb after issuing the 
ACTIVATE_DLC verb. This sequence assumes that the 
communication adapters will be open in case CNOS 
negotiation is required. 


If the session limit is greater than one, the application 
subsystem should issue the first CNOS for the special 
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mode named ‘SNASVCM@Q’ (EBCDIC characters). This 
special mode enables the establishment of a session on 
which to perform CNOS negotiation with the partner LU. 


CNOS must set the number of sessions before APPC/PC 
can start any conversations. 


Initiate transactions resulting from incoming 
ALLOCATEs (through the CREATE_TP exit or the 
GET ALLOCATE verb) or initiate a transaction locally 
by issuing a TP_STARTED verb. The transaction 
programs can now communicate with each other using 
conversation verbs. 


The TP_ENDED verb signals that the transaction 
program is ending its operation. 


The application subsystem must issue TP_ENDED before 
issuing DETACH_LU. 


Use the CNOS verb to lower the session limits (partner 
LU and mode name) to 0, which also causes deactivation 
of the sessions. The application subsystem must set the 
session limits for all partner LUs to 0 through CNOS 
before issuing DETACH _LU. 


The DETACH_LU or DETACH_ PU verbs enable the 
application subsystem to undefine local LUs, their partner 
LUs, and/or the PU. 


Starting a Transaction Program 


A transaction program may begin operating because of an 
action initiated at your local IBM PC or an action 
initiated by a remote partner. 


Locally Initiated Transactions 


A locally initiated transaction is initiated by an action at 
the local node, rather than by an incoming ALLOCATE. 
The application subsystem must issue a TP STARTED 
verb for each locally initiated transaction program to 
establish APPC/PC resources to support that program. 


The TP STARTED verb returns an identifer for the 
transaction program (TP_ID). All further verbs issued by 
the transaction program must include this TP_ID. The 
application subsystem must communicate the TP_ID to 
the transaction program after it receives the TP_ID from 
APPC/PC. For more information on the TP_ID identifier, 
see “Communicating Identifiers” on page 2-6. 


Remotely Initiated Transactions 


A transaction program operating at a remote node can 
initiate a transaction at the local node by issuing an 
ALLOCATE. This type of transaction is called a remotely 
initiated transaction. The remote LU sends a request for 
a transaction, called an incoming ALLOCATE, to the 
local node. The local node responds by accepting or 
rejecting the incoming ALLOCATE. 


If accepted, the incoming ALLOCATE establishes an 
initial conversation, and the local transaction program 
starts in RECEIVE state. 


Three options for managing transaction initiation from 
incoming ALLOCATEs are available: 


Option 1: Rejection 


The application subsystem rejects incoming ALLOCATEs. 
No exit routine is needed. 


Option 2: Synchronous Management 
The local LU queues incoming ALLOCATEs until you 


request one by issuing an ALLOCATE through a 
GET_ALLOCATE verb. APPC/PC assigns a TP_ID and 
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CONV_ID (conversation ID) at this time. The application 
subsystem should not issue a TP_ STARTED verb for a 
transaction program started by an incoming ALLOCATE. 
The application subsystem must communicate the TP_ID 
and CONV_ID parameters to the remotely initiated 
transaction program. For more information on the TP_ID 
and CONV_ID parameters, see “Communicating 
Identifiers” on page 2-6. 


A TP_VALID verb must follow the GET ALLOCATE to 
tell APPC/PC whether the transaction program is valid 
and correctly loaded. 


After APPC/PC accepts a request for a transaction 
program, you may choose to issue the CHANGE_LU verb 
to purge the incoming ALLOCATE queues for all LUs and 
then begin rejecting incoming ALLOCATEs. This 
procedure keeps the partner who issued the second 
ALLOCATE from waiting until the accepted transaction 
program is finished. In some cases this procedure avoids 
potential deadlocks. (For more information on resolving 
deadlocks, see “System Deadlocks” on page 10-2.) 


When the accepted transaction program ends, you should 
issue TP_ENDED to free APPC/PC resources for the 
transaction program and CHANGE_LU to resume 
queueing incoming ALLOCATEs. 


The GET_ALLOCATE verb does not suspend while 
waiting for an incoming ALLOCATE, but simply checks 
whether one is present (and optionally dequeues it). 
Therefore, you can use GET_ALLOCATE in a loop along 
with checking for input from the communication line, the 
keyboard, and other asynchronous devices. 


Issuing CNOS(PARTNER_LU_MODE_SESSION __ 
LIMIT = 0) does not deactivate all sessions immediately 
because each queued incoming ALLOCATE is using a 
session. The CNOS verb deactivates each session after 
you reject or service the incoming ALLOCATE using that 
session. Issue the CHANGE_LU verb to reject queued 
incoming ALLOCATEs. To service these incoming 
ALLOCATEs, continue issuing GET_ALLOCATE and 
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initiate the requested transactions until the DISPLAY 
verb indicates that no sessions remain active. 


Option 3: Asynchronous Management 


The application subsystem processes each incoming 
ALLOCATE as it arrives. You must provide an exit 
address for a routine that will validate and, if necessary, 
load the requested transaction program. APPC/PC 
assigns a TP_ID and CONV_ID at this time, so the 
application subsystem should not issue TP_STARTED for 
a transaction program started by an incoming 
ALLOCATE. The application subsystem must 
communicate the TP_ID and CONV_ID to the remotely 
initiated transaction program. 


When the transaction program ends, you should issue 
TP ENDED to free APPC/PC resources for the 
transaction program. 


For more information on asynchronous management of 
incoming ALLOCATKs, see “Managing Asynchronous 
Incoming ALLOCATEs (CREATE_TP Exit)” on 

page 2-12. 


Communicating Identifiers 


A transaction program must know the TP_ID and 

CONV _ID identifiers before it can issue valid verbs. 
Because the transaction program did not issue 

ATTACH _LU, it may not have direct access to the 
LU_ID it requires before it can issue the TP_STARTED 
verb. 


For a locally initiated transaction, the application 
subsystem can use the SET PASSTHROUGH and 
PASSTHROUGH verbs to communicate the TP_ID to the 
transaction program. (APPC/PC returns the CONV_ID 
on the ALLOCATE verb that starts each conversation.) 
Using the PASSTHROUGH and SET_PASSTHROUGH 
verbs, the application subsystem can define its own utility 
verb which, in turn, issues the TP_ STARTED verb, and 
returns the TP_ID to the transaction program. 
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For a remotely initiated transaction, the application 
subsystem can use the same utility verb to return both the 
TP_ID and CONV_ID without issuing the TP_STARTED 
verb. 


The utility verb will use the same interrupt mechanism 
that APPC/PC uses (INT X’68’). The application 
subsystem has to keep information obtained from files, or 
from its own menus, relating the transaction program 
names to the LU names and LU_IDs returned from the 
ATTACH_LU verb. See Appendix E, “Sample Programs” 
for an example of this technique. TP_INITIATHE, the 
sample utility verb described in Appendix E, is 
user-defined and not a part of APPC/PC. 


Communicating within the Application 
Subsystem 


It may also be necessary to communicate the LU_ID 
between portions of the application subsystem. For 
instance, one section of the application subsystem may 
issue the ATTACH _LU verb, and another manage 
incoming ALLOCATEs. The application subsystem may 
use the passthrough feature to perform this 
communication by having the incoming ALLOCATE 
routine request the LU_ID for a given LU name. The 
LU_ID would have been saved by the program that issued 
the ATTACH LU. For an example of communicating 
within the application subsystem, see 

Appendix E, “Sample Programs.” 


Supporting Multiple Transaction 
Programs 


APPC/PC assumes a single-tasking operating system in 
the IBM PC. If the transaction program issues a verb that 
suspends APPC/PC operation (such as 
RECEIVE AND_ WAIT if not enough data is available), 


2-7 


APPC/PC normally loops internally, returning to the 
transaction program only after the verb completes. Even 
if an interrupt occurs that permits the application 
subsystem or the transaction program to regain control, 
issuing a second APPC/PC verb is not valid until the 
actions resulting from the first have completed. With few 
exceptions APPC/PC requires serialized issuance of verbs. 


This single-threadedness does not prevent the existence of 
multiple transaction programs. 


Two approaches to providing a multiple transaction 
capability are: 


1. Code the transaction programs independently. 


A sophisticated application subsystem can help 
serialize the verbs from several transaction programs. 
For example, at appropriate points a transaction 
program might relinquish control so that other 
transaction programs can issue APPC/PC verbs. The 
application subsystem might provide runtime 
constructs (such as macros) for suspension of a 
transaction program. 


For designs where control might pass from one 
transaction program to another while a verb is being 
executed (for example, time slicing) the transaction 
programs can determine if APPC/PC is busy executing 
another verb. The transaction program can then loop 
on each verb until the verb that the transaction 
program is ready to issue can be executed. (The return 
code field contains a value which indicates that a verb 
has been rejected because APPC/PC was busy. For 
more information, see Appendix C, “Verb Return 
Codes.”) 


2. Code one program that emulates several transaction 
programs. For example, code a program that issues 
APPC/PC verbs using several TP_IDs. 


With either approach, problems can occur when 
communicating with a partner that does not support 
multitasking (such as another instance of APPC/PC). In 
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this case, using simultaneous multiple transaction 
programs can lead to a deadlock situation in which each 
side is blocked from sending because another transaction 
program is waiting to receive data. 


If you choose to develop an application subsystem that 
can support more than one transaction program 
simultaneously, you must analyze the communication 
topology and incoming ALLOCATE management to 
ensure that no deadlocks will occur. 


Deadlock situations between IBM PCs can be caused by 
an unfinished verb in a transaction program preventing 
the issuance of a verb in another TP in the same node. 


One way of preventing such deadlocks is to specify the 
RETURN_CONTROLUIINCOMPLETE) option on the 
ATTACH PU verb. This will cause control to return to 
the verb issuer with an INCOMPLETE return code if a 
verb cannot finish. Verbs from other transaction 
programs can then be issued before the incomplete verb is 
re-issued. 


If you select the RETURN_CONTROL(IINCOMPLETE) 
option of the ATTACH _PU verb, you should consider 
designing the application subsystem to perform all verb 
issuances. It can then perform a round-robin scheduling 
on the various TPs, including periodic re-issuance of 
incomplete verbs. See “System Deadlocks” on page 10-2 
for a more complete explanation of deadlocks. 


Using Application Subsystem 
Exits 


Three application subsystem exits are available for 
specification in the ATTACH _LU verb: 


1. An exit for LU-LU security that provides LU-LU 
passwords for an LU and a named partner LU 
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2. An exit that accepts errors logged during program 
execution (There is also an error log exit, primarily for 
hardware errors, specified on the ATTACH PU verb.) 


3. An exit that manages incoming ALLOCATEs and 
validates (and loads, if necessary) the requested 
transaction programs. 


Different LUs can use the same or different exit addresses. 
APPC/PC provides pointers to these asynchronous exits. 
These pointers give the application subsystem access to 
the appropriate verb (ACCESS _LU_LU_PW, SYSLOG, 

or CREATE TP). Unlike other APPC/PC verbs, these are 
passed from APPC/PC to the application subsystem. 


Supporting LU-LU Passwords 
(ACCESS_LU_LU_PW Exit) 


If LU-LU security is supported, the application subsystem 
must supply an exit routine for the verb 

ACCESS _LU_LU_PW. This exit routine provides the 
password that allows a specified partner LU to establish a 
session with a local LU. The application subsystem can 
maintain the passwords in a password table (preferably in 
encoded form), or the program can request them from the 
operator as needed. All security measures for passwords 
are the operator’s responsibility. For example, if you keep 
passwords on hard disk or diskette, consider what 
physical security is required to maintain confidentiality. 


Managing Logged Errors (SYSLOG Exit) 


If you wish to log the errors occurring during a 
conversation, you must provide an exit routine to accept 
such errors. You cannot issue another APPC/PC verb 
from this exit routine. 


If you specify this error log exit, you may want to print or 
display a console message, create a file of logged errors, 
or send an error message to another node. However, if 
the log message occurs during the processing of an 


2-10 


interrupt for incoming data, and the interrupted code is 
within DOS, then trying to use DOS to write to the 
console, a file, or a printer results in a recursive use of 
DOS, which leads to unpredictable results. 


Certain uses of BIOS within this exit may also lead to 
unpredictable or undesirable results, depending on the use 
of DOS and BIOS within the application. 


APPC/PC provides an interface to suspend operation. 
While APPC/PC operation is suspended, it will not call 
the SYSLOG exit (or any other APPC/PC exit). You may 
choose to have your application subsystem assume control 
of the DOS X’21’, BIOS X’10’, and BIOS X’17’ (and 
possibly other) interrupt vectors, and then disable 
APPC/PC (using the DISABLE/ENABLE_APPC verb) 
until the DOS or BIOS call is finished. The application 
subsystem should then regain control and re-enable 
APPC/PC (using the DISABLE/ENABLE_APPC verb). 
You can return control to the application subsystem from 
DOS or BIOS by re-establishing the interrupt vector and 
issuing your own INT X’21’, INT X’10’, or INT X’17’ (or by 
simulating the effect of these interrupts). The application 
subsystem then reassumes control of the interrupts and 
performs an IRET (Interrupt Return) to the transaction 
program. 


When enabled again, APPC/PC will process any delayed 
messages it received while it was disabled. 


The DOS Load and Execute call (X’4B’), which loads a 
transaction program and starts it executing, does not 
return until the transaction program finishes. Therefore, 
if APPC/PC is disabled at the beginning of this DOS call, 
you must find an opportunity to re-enable. Either do not 
disable APPC/PC for this call, or have each transaction 
program enable APPC/PC when the transaction program 
starts executing. The section on the sample program (see 
Appendix E, “Sample Programs”) discusses a user-defined 
TP_INITIATE verb that APPC/PC passes through the 
application subsystem. Although the sample program does 
not perform such re-enabling, this may be a convenient 
place to do it. 
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If your transaction programs use DOS or BIOS calls then 
you must either correct the recursion problem, or you 
should not use DOS or BIOS at the asynchronous exit. 


Managing Asynchronous Incoming 
ALLOCATEs (CREATE_TP Exit) 


If you accept incoming ALLOCATKs as they arrive, you 
must provide an exit to process them. 


One way of managing this is to start an application 
subsystem program that waits (by looping until a switch 
or counter is set) for an incoming ALLOCATE. When an 
incoming ALLOCATE arrives the looping program is 
interrupted by APPC/PC and the CREATE_TP exit is 
called. The CREATE_TP exit code sets the switch or 
counter and returns to APPC/PC. When the looping 
program regains control it ends the loop, then loads the 


requested transaction program and saves the TP_ID and 
CONV_ID. 


If your program does not support more than one 
simultaneous transaction program and a transaction 
program is running when the ALLOCATE arrives, you 
should either queue the incoming ALLOCATE at the 
CREATE_TP exit, or reject it. 


To support more than one simultaneous transaction, you 
can choose to pre-load all transaction programs and 
activate the appropriate one for each incoming request. 


Alternatively, you can use DOS to load the transaction 
programs at the CREATE_TP exit. You must suspend 
APPC/PC while using DOS to prevent DOS recursion. 
See “Managing Logged Errors (SYSLOG Exit)” on 
page 2-10 for a description of DOS recursion. 


If the asynchronous exit saves any data for access by 
another section of the application subsystem, then you 
should inhibit interrupts around the access code. 
Otherwise, a hardware interrupt might occur at the point 
of access, causing unpredictable results. 


2-12 


Canceling a Transaction 


You may wish to permit the operator to cancel a 
transaction by pressing Ctrl-Break on the keyboard. The 
DOS Control Break option in the APPC/PC menus 
specifies whether or not APPC/PC should issue a DOS call 
(“check keyboard status”) while it is suspended with no 
work. For example, APPC/PC has no work while the 
transaction program is waiting for data after issuing a 
RECEIVE AND_ WAIT verb. This DOS call does not 
cause DOS, used in this manner, recursion problems. 


If you select this option, the DOS Control Break routine 
gains control and cancels the transaction program when 
Ctrl-Break is pressed. However, APPC/PC is still in the 
middle of processing the RECEIVE_AND_WAIT verb, 
and cannot be used to process another verb. You can 
restore APPC/PC to a usable state by issuing the 
DETACH PU(TYPE=HARD) verb, which closes all 
adapters and cleans up APPC/PC conversations. In the 
environment just described, the operator has to start a 
utility program that issues DETACH _PU(TYPE=HARD). 


You can simplify the procedures for the operator by 
having the application subsystem substitute its own DOS 
Control Break routine (DOS interrupt X’23’) and then by 
issuing the DETACH PU verb from this routine. 
DETACH _PU overrides any existing verbs, regains 
outstanding storage, and closes the adapters. The routine 
should then execute the original DOS Control Break code 
to cancel the application. 


After canceling a transaction, the application subsystem 
must repeat the ATTACH PU, ATTACH _LU, 
ACTIVATE DLC, and CNOS sequence to redefine 
APPC/PC and restart the adapters. 


If the IBM PC is communicating with a host, the effect of 
an ungraceful shutdown of lines (and sessions) may result 
in Network Management messages flowing to a host 
application, alerting it to a potential problem. To prevent 
the user from causing these messages to flow to the host, 


you should prohibit the Ctrl-Break key from canceling an 
application. In this case, the application subsystem 
should substitute its own DOS Control Break routine, 
which ignores the Ctrl-Break key. If you choose this 
method, do not select the APPC/PC menu option “DOS 
Control Break.” 


Another possibility which may be desirable in some 
circumstances, is to use the BIOS keyboard Control Break 
routine (interrupt X’1B’) which takes effect immediately 
upon pressing the Ctrl-Break key. If you choose this 
method, do not select the APPC/PC menu option “DOS 
Control Break.” 


You must consider the total operating environment when 
choosing your method of cancelation. In particular, you 
must make sure that other resident programs that use the 
same interrupt are not affected. 


DOS Interrupts 


APPC/PC uses software interrupt X’68’ to issue verbs. The 
APPC/PC loader establishes this interrupt vector and the 
APPCUNLD program resets it. The application subsystem 
or the transaction program can determine if APPC/PC is 
loaded by comparing the character string starting at 9 
bytes before the address referred to in the X’68’ vector 
(location 416 in storage) to the ASCII character string 
“APPC/PC’. If the value matches, APPC/PC is loaded. 


Different adapters use different hardware interrupts. The 
SDLC adapter uses interrupts 3 and 4. The IBM 
Token-Ring Network adapter uses interrupt 2, 3, 6, or 7 
depending on the setting of switch 1 on the adapter card. 
For more information on this switch setting, see the IBM 
Token-Ring Network PC Adapter Guide to Operations. For 
more information on configuring APPC/PC for different 
adapters see the APPC/PC Installation and Configuration 
Guide. 
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Chapter 3. Developing a 
Transaction Program 


When developing a transaction program, you must choose 
between certain design alternatives. The following list 
describes the design issues to consider: 


e Choosing either basic or mapped conversations 


e Deciding whether to start conversations with or 
without confirmation 


e Choosing a name for the transaction program 
e Using the network management verb 
e Using the security features 


e Providing for conversion of ASCII names and data (if 
necessary). 


The first part of this chapter provides background 
information on the application protocols, conversation 
states, the APPC/PC support tasks, and data formats. The 
remaining parts of this chapter describe specific 
requirements for operating a transaction program. 


Understanding Application 
Protocols 


APPC/PC support enables your program to accomplish 
program-to-program communication. The design of your 
program depends on the protocols that you define and the 
communication that your program must accomplish. 
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In addition to any rules that you define for your program, 
APPC/PC defines rules that your program must follow 
when using a conversation. To enforce these rules, 
APPC/PC manages the state of your conversation and 
allows your program to perform certain operations only 
when the conversation is in the correct state. For 
example: 


e Your program cannot send data unless it has 
permission to send. 


e Your program cannot receive data unless the partner 
program has permission to send. 


e Your program cannot use a conversation after it has 
been deallocated. 


Understanding the Conversation 
States 


APPC/PC manages and enforces the following 
conversation states: 


State Definition 
Reset The conversation does not exist. 


Send The program can send data, request 
confirmation, or deallocate the conversation. 


Receive The program can receive information from the 
partner program. 


Confirm The program can reply to a confirmation 
request. 


Descriptions of state changes, and of the valid verbs that 


a transaction program can issue in each state, are 
contained in Chapter 6, “Using Transaction Mapped 
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Conversation Verbs,” and Chapter 7, “Using 
Transaction Basic Conversation Verbs.” 

Appendix B, “Conversation State Matrices,” summarizes 
the ways the state of a conversation can change. 


Understanding the Available 
APPC/PC Services 


APPC/PC support includes a series of services that your 
transaction program can use to communicate with another 
program. The following list includes the name of each 
service followed by a short description of the service and 
the names of the conversation verbs corresponding to the 
service: 


Allocate a Conversation 

Requests that the local LU start a conversation with a 
transaction program in a partner LU (the partner 
program). 


Corresponding verbs: ALLOCATE and MC_ALLOCATE. 


Send Data 
Sends data to the partner program. 


Corresponding verbs: SEND_DATA and 
MC_SEND_DATA. 
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Force Data in the Internal Buffers to be Sent 


Forces the LU to send to the partner program all data it is 
holding in an internal buffer. 


Note: You do not normally have to use this service to 
cause the LU to send the data. The LU automatically 
sends the data it stores in an internal buffer when the 
buffer is full or when it determines that your program is 
done sending. 


Corresponding verbs: FLUSH and MC_FLUSH. 


Receive Data 


Receives data from the partner program. 

Corresponding verbs: RECEIVE AND WAIT, 
RECEIVE_IMMEDIATE, MC_RECEIVE_AND_WAIT, 
and MC_RECEIVE_IMMEDIATE. 


Request Permission to Send 


Requests from the partner program permission to send 
data. 


Corresponding verbs: REQUEST_TO SEND and 
MC_REQUEST_TO_SEND. 
Grant Permission to Send 


Gives the partner program permission to send data. 


Corresponding verbs: PREPARE TO RECEIVE and 
MC_ PREPARE TO_RECEIVE. 
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Request Confirmation 


Requests that the partner program confirm that all the 
data has been received and processed successfully. 


Corresponding verbs: CONFIRM and MC_CONFIRM. 


Accept or Reject Confirmation 

Sends a reply to a confirmation request. 

Corresponding verbs: CONFIRMED, MC_CONFIRMED, 
SEND_ERROR, and MC_SEND_ERROR. 


Request to be Posted when Information is 
Available 


Requests that the LU post an event when the conversation 
has information available to be received. 


Corresponding verb: POST ON RECEIPT. 


Report an Error 

Reports that an error has occurred. 
Corresponding verbs: SEND ERROR and 
MC_SEND_ ERROR. 

Obtain Conversation Attributes 


Obtains the attributes of a conversation. These attributes 
include: 


e The name of the local LU 


e The name of the partner LU 
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e The mode name of the session’s transmission service 
mode 


e The type of confirmation protocols supported by the 
conversation 


e The type of conversation 


Corresponding verbs: GET ATTRIBUTES, 
MC_GET_ ATTRIBUTES, and GET_TYPE. 


Deallocate a Conversation 
Ends a conversation with the partner program. 


Corresponding verbs: DEALLOCATE and 
MC_DEALLOCATE. 


Choosing Between Basic and 
Mapped Conversations 


APPC/PC supports two types of conversations: basic and 
mapped. Mapped conversations are for transaction 
programs that are the final users of the data exchanged. 
A mapped conversation provides the features required for 
advanced program-to-program communication in an 
easy-to-use record-level manner. 


Basic conversations are for LU service transaction 
programs that provide services and exchange data for 
other transaction programs. A basic conversation has all 
the features of a mapped conversation but also has 
additional features that transaction programs may 
require to provide services for other applications. 


APPC/PC support provides separate sets of verbs for basic 


and mapped conversations. In general, mapped 
conversation verbs have fewer options and are easier to 
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use. Basic conversation verbs are more powerful and 
provide the additional flexibility required for use by an 
LU service program. 


You should consider the following topics when choosing 
between basic and mapped conversations. 


Understanding the Conversation 
Type 


The ALLOCATE verb designates a conversation as either 
a mapped conversation or a basic conversation. A 
program can issue only basic conversation verbs for a 
basic conversation. A program using a mapped 
conversation normally issues only mapped conversation 
verbs. 


You can provide your own mapped conversation support 
using only basic conversation verbs for a conversation 
designated as mapped. If you choose to provide your own 
mapped conversation support, your program must conform 
to the mapped conversation formats and protocols. 


See the SNA Format and Protocol Reference Manual: 
Architecture Logic for LU Type 6.2 for more information 
on mapped conversation formats and protocols. 


The verbs you use must be consistent for the entire 
conversation. You cannot use basic conversation verbs 
for some requests and mapped conversation verbs for 
other requests. APPC/PC rejects the verbs if you change 
from one type of verb to another within a conversation. A 
remotely intitated transaction program can issue the 
GET_TYPE verb to determine the conversation type. 


3-7 


Sending Data 


Use a basic conversation when you need to optimize your 
program’s performance by sending the data from a buffer 
that contains more than one logical record or a partial 
logical record. You can use this option to improve your 
program’s execution efficiency by enabling it to send 
several logical records with one request. 


To use this basic conversation feature, your program must 
provide a 2-byte length field (LL field) at the beginning of 
every logical record where: 
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The last 15 bits of the LL field contain a binary value 
equal to the length of the logical record, including the 
2-byte length field. The 15-bit limit restricts the value 
to a maximum of 32767 (82765 bytes of user data plus 
the 2-byte length field). If you use a value larger than 
32767, APPC/PC does not detect the error. APPC/PC 
uses the last 15 bits of the LL field even if the value is 
larger than 32767. 


The smallest value possible is 2 (the LL field followed 
by no data). If you use a value that is less than 2, 
APPC/PC indicates an error. 


APPC/PC ignores the first bit of the LL field. This bit 
is a concatenation indicator. If the concatenation 
indicator is set, the transaction program must append 
the data from the following logical record to the data 
received up to that point. This concatenation process 
should continue until the transaction program receives 
a record in which the concatenation indicator is not 
set. This definition provides for logical records that 
are longer than 32767 bytes. 


You must manage the reversal of byte values in your 
IBM PC. 


The IBM PC stores all numeric 16- or 32-bit values 
with the low-order (least significant) byte stored in the 
lower numbered address. Therefore, if a transaction 
program computes the length of a logical message and 


stores that value as the LL field, the 2 bytes appear in 
memory with the low-order byte first, and your IBM 
PC will send the bytes in this order (incorrectly!) over 
the communication line. 


The transaction program is responsible for putting all 
transaction-level data, including LL fields, in the 
correct order (high-order byte first). 


Use a mapped conversation if you do not need to send 
partial logical records, or more than one logical record. 
When you send data with the mapped conversation verbs, 
APPC/PC assumes that the buffer contains exactly one 
complete record. The mapped conversation support 
automatically provides length fields in the correct 
byte-reversed order and uses concatenated logical records 
as needed. 


Receiving Data 


Use a basic conversation when you need to receive more 
than one logical record in one buffer. This option can 
improve your program’s execution efficiency by enabling 
it to receive several logical records with one request (the 
BUFFER option). 


When you use this basic conversation feature, APPC/PC 
places the logical records in your buffer with the 2-byte 
LL fields intact. The bytes are reversed from normal IBM 
PC order. (See “Sending Data” on page 3-8 to find the 
format of this field.) 


Your program must examine the returned fields of the 
verb to determine if it has received a complete logical 
record and if so, where the next logical record begins. 
APPC/PC provides the rest of an incomplete logical 
record after a subsequent request to receive data. 


If you do not need to receive more than one record with a 
single request, use a mapped conversation. When you 
receive data with the mapped conversation verbs, 
APPC/PC ends the receive operation when your program 
receives a complete record (which may consist of several 
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concatenated logical records) or when your buffer is full. 
APPC/PC supplies a return code when it fills your buffer 
before your program has received a complete logical 
record. 


Your program can receive the rest of the logical record by 
issuing a subsequent request to receive data. The 
APPC/PC mapped conversation support removes any 
length fields and automatically concatenates records as 
necessary. 


Reporting Errors and Abnormal 
Termination 


Use a basic conversation for the following reasons: 


e To distinguish between errors detected by your 
program and errors detected by an application that is 
using your program 


e To distinguish between an abnormal termination 
caused by your program and one caused by an 
application using your program. 


When reporting an error or when abnormally terminating 
a conversation with an LU service program, the basic 
conversation verbs enable you to indicate which program 
detected the error. When the partner LU reports the error 
to the partner program with a return code, the value of 
the return code indicates where APPC/PC detected the 
error. 


If you do not need to distinguish between errors detected 
by your program and errors detected by other 
applications, use a mapped conversation. The mapped 
conversation verbs assume that your program detected the 
error. 
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Sending an Error Log Data Record 


Use a basic conversation to send a log record when you 
detect an error or abnormally terminate a conversation. 
The basic conversation verbs enable you to specify an 
error log general data stream (GDS) variable when you 
report an error or abnormally terminate a conversation. 
APPC/PC sends this log record to the local log and to the 
partner LU to be recorded in that log. This feature is 
useful when your program detects a critical or 
unrecoverable error and you want it to record the event to 
help determine the problem. 


If you send an error log GDS variable, the format of the 
record must conform to the formats defined by SNA. See 
SNA Reference Summary for more information on the 
error log GDS variable format. 


Use a mapped conversation if you do not need to send a 
log record when you detect an error or abnormally 
terminate a conversation. The mapped conversation verbs 
assume that your program does not need to record error 
data in the log to help determine the problem. 


Abnormally Terminating Because of 
a Time-out 


To indicate that your program has abnormally terminated 
the conversation because of a time-out condition, use a 
basic conversation. When abnormally terminating your 
conversation, the basic conversation verbs enable you to 
indicate that your program is abnormally terminating the 
conversation because the partner program has not done 
the necessary processing in the time allowed. When 
APPC/PC reports the error to the partner transaction 
program, the return code value indicates that a time-out 
condition caused the abnormal termination. 


If you do not need to report the cause of an abnormal 


termination, use a mapped conversation. The mapped 
conversation verbs assume that your program requested 
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the abnormal termination because of a critical or 
unrecoverable error. 


Requesting Confirmation 


Requesting confirmation is an efficient way to determine 
that the partner program has received all the data sent so 
far. If you plan to request confirmation during the 
conversation, the allocating transaction must indicate this 
fact when you request the allocation of the conversation. 


If you use conversation protocols that do not request 
confirmation, you should not request the allocation of a 
conversation supporting confirmation services. 


You can write a transaction program that participates in 
conversations that use confirmation requests and 
conversations that do not use confirmation requests. 


Choosing a Transaction Program 
Name 


When you name a transaction program, choose a name 
that has a first character with an EBCDIC code greater 
than an EBCDIC blank (X’40’). Transaction program 
names containing first characters with EBCDIC codes less 
than X’40’ are reserved for LU service programs that are 
defined by SNA. Transaction program names can include 
up to 64 characters. 
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Using the Network Management 
Verb 


You can send network management information to a host 
application. In addition, you can log such information 
locally. The network management verb enables you to 
report local I/O errors such as disk errors. APPC/PC 
sends IBM Token-Ring Network errors to the host 
automatically, provided the IBM PC successfully 
establishes a connection with the host. 


Using the Security Features 


APPC/PC provides two types of security function: 
partner-LU verification and end-user verification. 
Partner-LU verification is a session-level security protocol 
that takes place at the time the session is activated. 
End-user verification is a conversation-level security 
protocol that takes place at the time a conversation is 
started. The ATTACH_LU verb specifies the level of 
security. 


Partner-LU Verification 
(Session-Level Security) 


Partner-LU verification is performed by an exchange of 
security information between the two LUs. This exchange 
is called LU-LU verification. This level of security is 
generally required when the communications network is 
not physically secure. The local LU and the remote LU 
each provide their password and APPC/PC performs 
encryption for password verification. 


Passwords are established by the application subsystem 


and are passed to APPC/PC when requested, using the 
ACCESS_LU_LU_PW verb. LU-LU passwords are 
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established for each LU pair. It is recommended, but not 
required, that each LU pair have a unique password. 


End-User Verification 
(Conversation-Level Security) 


End-user verification is used to enable the requested LU 
to verify the identity of the requester before providing 
access to the requested transaction program and its 
resources. The security information exchanged can 
include a user ID and a password. The user IDs provided 
by conversation-level security can also be used for 
auditing and accounting purposes. 


In conversation-level security the requesting transaction 
program provides the security information on the 
ALLOCATE verb and the remote application subsystem 
performs the verification. (See ALLOCATE and 
MC_ALLOCATE verb descriptions). If the requesting 
transaction program has not supplied the correct user ID 
and password, the remote application system rejects the 
request. 


An intermediate transaction program (one started by 
another transaction program) that requires 
conversation-level security may be used to access an 
additional transaction program that requires 
conversation-level security. In this case, an 
already-verified indicator is set in the allocation request 
for the additional transaction program. The user ID saved 
from the first request which initiated the intermediate 
transaction program is automatically supplied in the 
second request. 
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Converting between EBCDIC and 
ASCIT 


APPC/PC assumes that the interface between it and the 
transaction program (or the application subsystem) uses 
EBCDIC characters. Your program may send some data 
or parameters to a system services control point (SSCP) or 
partner LU where they will be compared to table values 
expressed in EBCDIC. These values include the 
transaction program name, the partner LU name supplied 
on ALLOCATE, the mode name, the network identifier 
supplied on the ATTACH_PU verb, the user ID, and the 
user password. 


Incoming names are in EBCDIC, and your program must 
translate them to ASCII (if the application subsystem 
stores them in ASCII). Therefore, both the application 
subsystem and the transaction program must be prepared 
to perform ASCII-to-EBCDIC conversion. 


Do not yield to the temptation to define private protocols 
between two IBM PCs which avoid this conversion. 
Private protocols can cause unexpected difficulties and 
hamper communication with other types of computers. 
For example, protocol errors or problems with 
unrecognized names can result from the use of an ASCII 
“K” (X’4B’) on an LU or net name. The EBCDIC period 
used in a fully qualified name also has the value X’4B’. 


The following names must be eight EBCDIC characters 
long (padded on the right with blanks if the name is less 
than 8 characters). These names must be Type A symbol 
strings (uppercase letters; numerics; or the special 
characters $, #, and @, with the first character not a 
numeric.) 


LU_NAME 
MODE_NAME 
NET_NAME 
PARTNER_LU_NAME 


Whether a transaction program needs to translate data 
depends on private agreement between the partner 
transaction programs. If your program is communicating 
with a node that normally uses EBCDIC, you should 
convert data to EBCDIC as appropriate. 


As a convenience, APPC/PC provides a verb (CONVERT) 


that converts ASCII codes to EBCDIC or EBCDIC codes 
to ASCII. 
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Chapter 4. Introduction to 
APPC/PC Verbs 


A transaction program communicates with other 
transaction programs by issuing conversation verbs. Just 
as conversation verbs provide a mechanism for 
communication between transaction programs, other verbs 
communicate requests to the internal components of 
APPC/PC. For example, these requests control resources, 
such as conversations and sessions, available to and 


provided by APPC/PC. 


Verb Types 


The different types of verbs that APPC/PC recognizes and 
issues can be classified into the following categories: 


Control verbs 

Mapped conversation verbs 
Basic conversation verbs 
Network management verb 
Other verbs. 


Control Verbs 


A few verbs, called control verbs, provide a system 
definition capability. The application subsystem uses 
these verbs to attach and detach the PU and LUs, to start 
and end locally initiated transaction programs, and to 
determine local parameter settings. 


In addition, APPC/PC issues three other control verbs 
(CREATE TP, SYSLOG, and ACCESS LU _LU_PW) to 
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the application subsystem. These verbs request an action 
from the application subsystem. See Chapter 5, “Using 
Control Verbs,” for detailed descriptions of the control 
verbs. 


Mapped Conversation Verbs 


A transaction program uses mapped conversation verbs to 
exchange arbitrary data records with other transaction 
programs, in any format on which the programmers agree. 
See Chapter 6, “Using Transaction Mapped Conversation 
Verbs,” for detailed descriptions of the mapped 
conversation verbs. 


Basic Conversation Verbs 


A transaction program uses basic conversation verbs to 
exchange records containing a 2-byte length prefix with 
other transaction programs. 


End-user transaction programs typically use mapped 
conversations. Service transaction programs typically use 
only basic conversations. See Chapter 7, “Using 
Transaction Basic Conversation Verbs,” for detailed 
descriptions of the basic conversation verbs. 


Network Management Verb 


A transaction program uses the Network Management 
Verb (TRANSFER _MS_DATA) to provide management 
information to a network management services function 
connected to an SNA network. The network management 
services function uses this information to help manage the 
network to which this SNA node belongs. See 

Chapter 8, “Using the Network Management Verb,” for a 
detailed description of the network management verb. 
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Other Verbs 


APPC/PC also supports five miscellaneous verbs: 


e CONVERT 

e DISABLE/ENABLE_APPC 
e SET_PASSTHROUGH 

e PASSTHROUGH 

e TRACE. 


See Chapter 9, “Other APPC/PC Services,” for detailed 
descriptions of these verbs. 


Verb Descriptions 


The following verb syntax shows the function and 
information content of the interactions between 
transaction programs and APPC/PC. The transaction 
verbs, (the mapped conversation and basic conversation 


verbs) are described in Chapters 6 and 7 respectively. The 


user must perform the actual encoding. The following 
syntax is for descriptive purposes only. 
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General Description 


Each transaction program verb is associated with 
information relative to its function. This information 
consists of: 


Supplied parameters 

Returned parameters 

Return codes 

Error conditions associated with each verb. 


The rest of this chapter refers to the following sample 
verb description. The name of the verb occupies the left 
side of the figure in an area of its own. In the sample, the 
name of the transaction program verb is “VERB _ NAME.” 


Supplied Parameters: 
VERB_NAME VARIABLE (variable) 


CONSTANT (VALUE_1) 


(VALUE_2) 
Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters 


With each verb are several parameters that the 
transaction program uses to supply information to 
APPC/PC. The top area at the right side of the sample 
verb description identifies each parameter the transaction 
must supply with that verb. Following each parameter 
name, the verb description identifies the kind of 
parameter value expected by APPC/PC. In general, there 
are two kinds of supplied parameters: parameters that 
have a variable parameter value, and parameters that 
have a limited choice of constant values. 


The sample verb description includes two supplied 
parameters named VARIABLE and CONSTANT. 
VARIABLE is a supplied parameter with a value that the 
transaction program needs to define. 
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The other supplied parameter, CONSTANT, has a more 
limited range of possible values. A constant parameter 
can take only the values listed in the verb description, in 


this case VALUE_1 or VALUE_ 2. 


Returned Parameters 


In addition to supplied parameters, there is a list of 
parameters that APPC/PC returns to the transaction 
program after it finishes executing the verb. These 
returned parameters provide information about the result 
of the verb execution, with details to inform the 
transaction program about possible conversation state 
transitions, or problems that APPC/PC encountered while 
executing the verb. 


Return Codes 


Most transaction program verbs include a return code as 
one of the returned parameters. APPC/PC places a value 
in the return code that indicates the success or failure of 
the request. 


Detailed parameter descriptions immediately follow each 
verb description. 


Error Conditions 


Each of the transaction program verbs recognized by 
APPC/PC has unique error conditions that can occur 
during verb execution. The possible error conditions that 
APPC/PC can encounter during verb execution are 
identified and discussed in detail in the list of returned 
parameter descriptions. 
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Chapter 5. Using Control Verbs 


The application interface to APPC/PC includes control 

verbs the application subsystem used to manage the node. 
These control verbs do not transfer program data over the 
communication line, but perform the following operations: 


e Define the PU 


e Define local LUs (the LU name, potential LU partners, 
and the parameters defining the sessions between LUs) 


e Start a local transaction program 
e Process asynchronous events detected by APPC/PC 
(for example, incoming ALLOCATEs from partner LUs 


or information for the system log caused by hardware 
alerts or received log messages). 


5-1 


The diagram below shows the relationship of the control 
verbs to the application subsystem and APPC/PC. The 
arrows in this figure show which control verbs the 
application subsystem sends to APPC/PC and which 
control verbs APPC/PC sends to the application 


subsystem. 
Application 
Subsystem 


ACTIVATE DLC A 

ATTACH LU ACCESS LU LU PW 
ATTACH PU CREATE TP 
CHANGE LU SYSLOG 

CNOS 

DETACH LU 

DETACH PU 

DISPLAY 

TP STARTED 

TP ENDED 


v 
APPC/PC 


The rest of this chapter describes the operation of each of 
the control verbs. See Chapter 4, “Introduction to 
APPC/PC Verbs,” for a description of the different verb 
types and an explanation of the format used in the verb 
descriptions. 
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Understanding Control Verb 
Return Codes 


All control verbs that a program can issue have a 
parameter called RETURN_CODE that APPC/PC uses to 
pass a return code back to the program after it executes 
(or attempts to execute) a verb. The return code indicates 
the results of verb execution. APPC/PC returns only one 
return code at a time. 


Appendix C, “Verb Return Codes,” provides detailed 
information on all return codes, including the actions you 
should take. The following return codes can be returned 
on almost any verb. 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
INCOMPLETE 
OK. 


Detailed descriptions of these return codes follow. Brief 
references to these return codes appear in the individual 
verb descriptions later in this chapter. 


e APPC_ABENDED indicates that APPC/PC has been 
abnormally terminated. 


e APPC_BUSY indicates that APPC/PC is currently 
executing another verb and cannot execute this verb. 
This error can occur if a verb is issued after APPC/PC 
execution is interrupted (for example, by a Ctrl-Break 
or timer interrupt). 


e APPC_DISABLED indicates that APPC/PC is disabled 
as a result of the DISABLE/ENABLE_APPC verb. 


e INCOMPLETE indicates that APPC/PC has not 
finished executing the verb but is returning control so 
that you can issue verbs for other transaction 


programs. The only control verbs that return this code 
are TP_ENDED and TP_VALID. APPC/PC returns 
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this indication only if you specify 
RETURN_CONTROL(INCOMPLETE) on the 
ATTACH PU verb. 


OK indicates that APPC/PC executed the verb 
successfully. That is, APPC/PC performed the 
function defined for the verb, up to the point at which 
it returns control to the program. 


Application Subsystem to 
APPC/PC 


The application subsystem uses the following verbs to 
request actions from APPC/PC: 


ACTIVATE_DLC 


Activates a DLC adapter. The application subsystem must 
issue an ACTIVATE DLC verb for each DLC adapter 
installed in the IBM PC. Before issuing ACTIVATE_DLC 
verbs, the application subsystem should issue the 
ATTACH_LU verbs to define the LUs before traffic 
arrives on the adapter. 


Supplied Parameters: 


ACTIVATE _DLC DLC_NAME (ITRN) 
(SDLC) 


ADAPTER_NUMBER (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


DLC_NAME specifies the name of the adapter that the 
application subsystem is activating. 


e ITRN: specifies the IBM Token-Ring Network adapter. 


e SDLC: specifies the IBM Synchronous Data Link 
Control adapter. 


ADAPTER NUMBER specifies whether the IBM 
Token-Ring Network adapter is configured as a primary or 
secondary adapter. Set this value to 0 if the specified 
adapter is the primary IBM Token-Ring Network adapter 
or 1 if it is the secondary adapter. The adapter is 
configured as a primary/secondary adapter if switch 2 on 
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the adapter card is set to the primary/secondary position. 
For use with an SDLC adapter, set the 
ADAPTER NUMBER value to 0. 


Returned Parameters: 


RETURN_CODE indicates whether the 
ACTIVATE DLC verb is acceptable (0) or not acceptable 
(non-0). If the verb is not acceptable, APPC/PC does not 
activate the adapter. The ACTIVATE DLC return codes 
are as follows: 


e NO_PU_ATTACHED: APPC/PC has not yet received 
a valid ATTACH _PU verb 


e UNRECOGNIZED DLC: APPC/PC could not find the 
specified DLC name and number. 


e DUPLICATE DLC: The specified DLC is already 
activated 


e DLC_FAILURE: APPC/PC could not activate the 
specified DLC. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3, and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 
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ATTACH_LU 


Requests APPC/PC to define a local LU with the specified 
parameters. These parameters include the set of partner 
LUs (and mode names) for which APPC/PC can build 
sessions. The application subsystem must use this verb to 
define all connections to partner LUs. 


The LU name, partner LU names, and mode names must 
each be 8 characters long (padded on the right with 
blanks if the names are less than 8 characters) using 
uppercase letters; numerics; or the special characters $, #, 
and @. (The first character cannot be numeric.) 


The LU can have several partners and several modes 
defined for each partner. You must repeat the 
PARTNER_LU and PARTNER SESSION_LIMIT 
parameters for each partner LU you define relative to the 
local LU_NAME. In addition, you must repeat the 
parameters relating to MODE_ NAME (MODE_NAME 
through 

MODE_MAX NEGOTIABLE _SESSION_LIMIT) for 
each mode name defined for the particular 
PARTNER_LU. The indentation within the following 
table indicates that you can specify multiple partner LUs 
for each local LU and multiple mode names (and other 
parameters) for each partner LU. 
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Supplied Parameters: 
ATTACH_LU LU_NAME (variable) 


LU_LOCAL_ADDRESS (variable) 
LU_SESSION_LIMIT (variable) 
CREATE _TP_EXIT (variable) 
SYSTEM _LOG_EXIT (variable) 
LU_LU_PASSWORD_EXIT (variable) 
MAX TPS (variable) 


QUEUE_ALLOCATES (YES) 
(NO) 


QUEUE_DEPTH (variable) 

. PARTNER_LU_NAME (variable) 
.-PARTNER_LU_SESSION_LIMIT (variable) 
. -PARTNER_LU_MAX MC_SEND_LL (variable) 


- PARTNER_LU_DLC_NAME (variable) 


. PARTNER_LU_ADAPTER_NUMBER (variable) 


. -PARTNER_LU_ADAPTER_ADDRESS 
(variable) 


.-PARTNER_LU_SECURITY_CAPABILITIES 
(variable) 


...-MODE_NAME (variable) 


-..-MAX RU_SIZE 
(variable : variable) 


...-PACING SIZE (variable) 


-..-MODE_MAX NEGOTIABLE_SESSION_LIMIT 
(variable) 


Returned Parameters: 
RETURN_CODE (variable) 


LU_ID (variable) 
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Supplied Parameters: 


LU_NAME specifies the local LU’s network name (in 
EBCDIC), that is, the name of the LU as known to the 
network. 


LU_LOCAL_ADDRESS specifies the local SNA (NAU) 
address of this LU (as defined in VTAM and NCP when 
connected to a host). This address should be set to zero 
for LUs that establish only peer-to-peer sessions. 


LU_SESSION_LIMIT specifies the maximum number of 
sessions you want to permit between the local LU and 
other partner LUs. 


CREATE_TP_EXIT specifies the address of the 
application subsystem code to process incoming 
ALLOCATEs (in SNA terms, ATTACHes or FMH-5s) from 
partner LUs. If you do not wish to accept any incoming 
ALLOCATES, the application subsystem must set this 
parameter to all 1s (X’FFFFFFFF’). In this case, 
APPC/PC rejects any incoming ALLOCATEs. 


SYSTEM _LOG_EXIT specifies the address of the 
application subsystem code to process log messages sent 
from the partner LU or transaction program, or generated 
locally from detected protocol errors. If you do not wish 


to process any of these types of errors, you should set this 
parameter to all 1s (X’FFFFFFFF’). 


Warning: You must provide a log exit if you want 
APPC/PC to provide notification or error information. 


LU_LU_PASSWORD_ EXIT specifies the address of the 
application subsystem code to supply the LU-LU password 
for the given partner LU. If you do not plan to support 
LU-LU verification security, you should set this 
parameter to all 1s (X’FFFFFFFF’). 


MAX_TPS specifies the maximum number of transaction 
programs that APPC/PC can run under this LU. 
APPC/PC rejects an incoming ALLOCATE or a 
TP_STARTED verb if it has already initiated this 
maximum number. 
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QUEUE_ALLOCATES specifies whether or not you 
want the LU to queue incoming ALLOCATEs, and return 
them one at a time each time the application subsystem 
issues a GET_ ALLOCATE verb. 


e YES: Set the CREATE TP EXIT parameter to all 0s 
(X’00000000’) to direct the LU to queue incoming 
ALLOCATEs. 


e NO: Set the CREATE _TP_EXIT parameter to the 
address of the application subsystem code to process 
incoming ALLOCATEs. 


QUEUE_DEPTH specifies the maximum number of 
incoming ALLOCATEs for the LU to queue. APPC/PC 
rejects incoming ALLOCATEs that occur when it already 
has this number of ALLOCATEs in the queue. This 
parameter applies only if QUEUE_ALLOCATES= YES is 
also specified. 


PARTNER LU_NAME specifies the network name (in 
EBCDIC) of the remote LU that the application subsystem 
is defining as a partner. If the name is less than 8 
characters long, the application subsystem must pad it 
with EBCDIC blanks on the right. 


PARTNER _LU_SESSION_LIMIT specifies the 
maximum number of sessions, across all mode names, you 
want to permit between the local LU and the specified 
partner LU. This value should be greater than 1 only if 
the partner LU supports parallel sessions. 


PARTNER LU MAX MC SEND _LL specifies the 
maximum size of a logical record (as indicated by the LL 
field of the logical record) you want the mapped 
conversation function to construct (used only in a mapped 
conversation). Use the default of zero, which implies the 
largest possible value (82767), unless the partner requires 
a smaller value. The minimum value is 4. A value of 1, 2, 
or 3 is treated as if it were a 4. 


PARTNER_LU_DLC_NAME specifies the name of the 


DLC used to communicate with the partner LU. This 
parameter must be the name specified on the APPC/PC 
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configuration menu for DLC parameters. Use “SDLC” for 
SDLC operation or “ITRN” for operation with the IBM 
Token-Ring Network. Use ASCII characters for this 
name; it is used locally only. 


PARTNER _LU_ADAPTER_ NUMBER specifies 
whether the IBM Token-Ring Network adapter used for 
this partner LU is primary or secondary. The value of 
this is 0 if the adapter is configured as the primary 
adapter, and 1 if it is configured as the secondary adapter. 
The adapter is primary or secondary if switch 2 on the 
adapter card is set to the primary/secondary position. The 
parameter must match the specification on the APPC/PC 
configuration menu for the IBM Token-Ring Network. 
The value of this parameter must be 0 for SDLC. 


PARTNER_LU_ADAPTER_ ADDRESS specifies the 
adapter address of the partner LU. If the partner node is 
running under APPC/PC on the IBM Token-Ring 
Network, this value is the one entered in the Local Node 
Address field of the APPC/PC configuration menus. This 
address is not used for SDLC operation. 


PARTNER _LU_SECURITY_CAPABILITIES specifies 
the LU-LU verification and conversation security support 
levels of the partner LU. There are three security 
functions that you may or may not choose to support: 


1. LU-LU Verification Security: 
Indicates that the application subsystem provides the 
LU-LU password for APPC LU-LU verification. 
APPC/PC provides the verification logic. 


2. Conversation Level Security: 


Indicates that the application subsystem validates the 
conversation-level password and user ID. 


3. Already Verified: 


Indicates automatic acceptance of the incoming 
ALLOCATE where the partner LU has already verified 
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the password and user ID (permitted only if the 
conversation supports conversation level security). 


MODE_NAME specifies the mode name (in EBCDIC) 
designating the network properties (such as the maximum 
RU size and pacing windows) for these sessions. If the 
name is less than 8 characters long, the application 
subsystem must pad the name with EBCDIC blanks on the 
right. The partner LU must have the same mode name 
defined. 


MAX RU_SIZE(ow:high) specifies the range of 
permissible maximum RU sizes to be used on sessions with 
this mode name. When the local LU is the session 
initiator, APPC/PC tries to use the high value, but the 
partner LU may negotiate the value to a lower value 
during session activation. APPC/PC rejects the session 
activation if the negotiated value falls outside the 
specified range. When the local LU does not initiate the 
session, APPC/PC accepts unchanged the incoming 
maximum RU size value if it falls within the range. If it 
does not fall within the range, APPC/PC negotiates to the 
nearest value that is within the range (that is, either the 
high or low value). 


Although the low value can be as low as 16, APPC/PC 
gains no advantage from values less than 256. You should 
specify a value less than 256 only if the partner LU gains 
some efficiency from the smaller value. In the most 
general environment, you should specify the value 
according to the following expression: 


low value < 256 < high value 


APPC/PC transmits the MAX _RU_SIZE to the remote 
LU in an encoded form. The formula for this encoding is: 


ax 2b 8<a<l1l6 


where “a” is the mantissa and “b” is the exponent of the 
MAX _RU_SIZE value. APPC/PC rounds down any value 
that it cannot encode in this form. The following table 
lists the values that can be encoded in this form. 
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-- re 


ao) ay (13) (3) a4) (15) 


1024 1152 1280 1408 1536 1664 1792 1920 
2304 2560 2816 3072 3328 3584 


PACING_SIZE specifies the largest permissible receive 
pacing window size on sessions of the specified mode 
name. The largest possible value is 63. A value of 0 
implies no pacing (specifying an infinite window size). 
When the local LU initiates the session, APPC/PC tries to 
use this value, but the partner LU may negotiate the 
value to a lower value during session activation. 


When the local LU is not the session initiator, APPC/PC 
accepts unchanged the incoming receive pacing value if it 
is less than the specified value. If the incoming receive 
pacing value is greater than the specified value, APPC/PC 
negotiates the incoming value down to the specified value. 


MODE _ MAX NEGOTIABLE _SESSION_LIMIT 
specifies the maximum number of sessions you want to 
permit during CNOS negotiation. This parameter sets an 
upper bound on the maximum number of sessions that can 
be specified between the local LU and the partner LU on 
this mode for a locally issued CNOS verb with 
SET_NEGOTIABLE(NO). This parameter also limits the 
maximum number of sessions. See “CNOS (Change 
Number of Sessions)” on page 5-23 for information on the 
effects of session limits. 
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Returned Parameters: 


RETURN_CODE indicates whether the verb is 
acceptable (0) or not acceptable (non-0). If the verb is not 
acceptable, APPC/PC does not define any part of the local 
LU. To indicate errors detected in the definition of a 
particular partner LU or mode name, APPC/PC overwrites 
the erroneous field with dollar signs ($). 


See Appendix C, “Verb Return Codes,” for more 
information on return codes. 


The ATTACH_LU return codes are as follows: 


e NO_PU_ATTACHED: The application subsystem has 
not yet issued an ATTACH PU verb. 


e ALREADY ACTIVE _LU: The LU_NAME is defined 
already. 


e BAD _ PART SESS: The session limit for an individual 
partner LU (PARTNER LU_SESSION_LIMIT) is 
greater than the session limit permitted for all partner 
LUs (LU_SESSION_LIMIT). 


e BAD RU_SIZES: The second value of the 
MAX_RU_SIZE parameter is smaller than the first 
value. Reversing the values is the most likely solution 
for this error. 


e BAD MODE_ SESS: The session limit for an 
individual mode name (MODE_SESSION_ LIMIT) is 
greater than the session limit permitted for all mode 


names used for sessions with the specific partner LU 
(LU_SESSION_LIMIT). 


e BAD_PACING_CNT: The PACING_SIZE is not 


between 0 and 63, inclusive. 
e EXTREME_RUS: The upper bound for the 


MAX_RU_SIZE is too large or the lower bound is too 
small. 
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SNASVCMG_1: APPC/PC does not accept 
“SNASVCMG” as the mode name for a single session 
connection to communicate data between transaction 
programs. 


UNRECOGNIZED_DLC: The specified DLC name and 
ID could not be found in the configuration file. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3. 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


LU_ID specifies the LU identifier. This value is used in 
subsequent application subsystem and conversation verbs 
to identify the local LU. 


Notes: 


1. 


After the application subsystem defines the local and 
partner LUs, it must still issue the CNOS verb before 
APPC/PC permits any incoming session activations or 
outgoing ALLOCATKs, for both parallel and single 
session connections. 


The application subsystem can redefine the 
connections between the local LU and its partner LU 
by issuing the DETACH _LU verb, and then supplying 
the new parameters with another ATTACH LU verb. 
The CHANGE _LU verb can redefine only a few of 
these parameters. 


A session activation request received from a remote 
LU might not specify a local LU name. If the 
application subsystem specifies a null (all EBCDIC 
blanks) local LU name in an ATTACH_LU verb, 
APPC/PC directs the session activation request to that 
local LU. If the application subsystem does not specify 
a null local LU name on an ATTACH_LU verb, 
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APPC/PC directs the session activation request to the 
first local LU defined through an ATTACH_LU verb. 


4. When defining an LU that can perform parallel 
sessions, you should define the “SNASVCMG?” (in 
EBCDIC) mode name for any partner LUs allowing 
parallel sessions (that is, where the value of the 
PARTNER_LU_SESSION_LIMIT parameter is 
greater than 1). If you do not explicitly define this 
mode, APPC/PC does it implicitly, using default 
settings for RU size (256), pacing window (1), and 
session limit maximum (2). APPC/PC subtracts the 
number of sessions reserved for the “SNASVCMG” 
mode from the number of sessions allowed by the 
local-LU and partner-LU session limits when changing 
the number of sessions with CNOS. 


5. You must provide the LU_NAME, 
PARTNER_LU_ NAME, and MODE_ NAME 
parameters in EBCDIC because APPC/PC transmits 
them to the remote LU. You can use the CONVERT 
verb to convert these parameters from ASCII to 
EBCDIC. 
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ATTACH_PU 


Requests APPC/PC to define a local PU with the specified 
parameters. 


Supplied Parameters: 
ATTACH_PU PU_NAME (variable) 


NET_NAME (variable) 
SYSTEM_LOG_ EXIT (variable) 


RETURN_CONTROL (COMPLETE) 
( INCOMPLETE ) 


Returned Parameters: 
RETURN_CODE (variable) 
VERSION (variable) 


RELEASE (variable) 


Supplied Parameters: 


PU_NAME specifies the local PU’s network name; that 
is, the name of the PU, as known in its network. 
APPC/PC returns the PU_NAME on error messages 
logged to the PU SYSLOG exit. The PU_NAME is not 
used elsewhere. 


NET_NAME specifies the name (in EBCDIC) of the 
network containing this PU. 


SYSTEM _LOG_EXIT specifies the address of the 
application subsystem code to process log messages 
destined for the PU; for example, detected protocol or 
hardware errors, or network management messages. If 
you do not want APPC/PC to call the application 
subsystem to process any of these types of messages, set 
this parameter to all 1s ( X’FFFFFFFF’). 


Warning: You must provide a log exit if you want 
APPC/PC to provide notification or error information. 
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RETURN_CONTROL indicates whether to return 
control for certain verbs to the verb issuer with an 
INCOMPLETE return code if APPC/PC cannot 
immediately finish processing the verb. This option 
enables APPC/PC to execute verbs from other transaction 
programs to prevent deadlock problems. For more 
information, see “System Deadlocks” on page 10-2. 


e COMPLETE: Specifies that each verb is to be 
processed to completion. 


e INCOMPLETE: Specifies that the verbs that return 
an INCOMPLETE return code must be re-issued 
without change. Each verb description shows, under 
“Returned Parameters”, whether INCOMPLETE is a 
possible return code for that verb. 


Returned Parameters: 


RETURN_CODE indicates whether the verb is 
acceptable (0) or not acceptable (non-0). If the verb is not 
acceptable, APPC/PC does not define any part of the local 
PU. See Appendix C, “Verb Return Codes,” for more 
information on return codes. The ATTACH _PU return 
codes are as follows: 


e ALREADY_ACTIVE_PU: The PU is already active 
and cannot be redefined at this time. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


VERSION specifies the version number of this APPC/PC 
implementation. 


RELEASE specifies the release number of this APPC/PC 
implementation. 
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Notes: 


1. After initially loading the system or issuing 
DETACH_PU, the application subsystem must issue 
the ATTACH _PU verb before issuing any other 
application subsystem or conversation verbs. 


2. You must provide the NET_NAME parameter in 
EBCDIC because APPC/PC transmits it to the remote 
LU. You can use the CONVERT verb to convert this 
parameter from ASCII to EBCDIC. 
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CHANGE_LU 


Alters parameters for an existing local LU. 


Supplied Parameters: 

CHANGE_LU LU_ID (variable) 
CREATE_TP EXIT (variable) 
SYSTEM_LOG_EXIT (variable) 
LU_LU_PASSWORD_EXIT (variable) 


MAX TPS (variable) 


QUEUE_ALLOCATES (STOP) 
(RESUME ) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


LU_ID specifies the identifier for the local LU that the 
application subsystem is altering. APPC/PC returned this 
value when it identified and initialized the LU using 
ATTACH _LU. For more information, see 

“ATTACH LU” on page 5-7. 


CREATE_TP_EXIT specifies the address of the 
application subsystem code that processes incoming 
ALLOCATEs from partner LUs. If you do not want the 
application subsystem to accept any incoming 
ALLOCATEs, set this parameter to all 1s (X’FFFFFFFF’). 
In this case, APPC/PC rejects any incoming ALLOCATEs. 


The application subsystem must not change the method of 
handling incoming ALLOCATEs. If the application 
subsystem specified synchronous management (queueing) 
of incoming ALLOCATEs in the ATTACH_LU verb (by 
setting CREATE TP EXIT to 0), it must also specify this 
synchronous management with CHANGE_LU. If the 
application subsystem specified asynchronous 
management using the CREATE_TP exit of incoming 
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ALLOCATEs in the ATTACH _LU verb, then it must 
specify asynchronous management with CHANGE_LU. 


SYSTEM LOG_EXIT specifies the address of the 
application subsystem code that processes log messages 
sent from the partner LU or transaction program, or 
generated locally as a result of detected protocol errors. 
If you do not want APPC/PC to call the application 
subsystem to process these types of errors, set this 
parameter to all 1s (X’FFFFFFFF’). 


LU_LU_PASSWORD_ EXIT specifies the address of the 
application subsystem code that is to supply the LU-LU 
password for the given partner LU. If the session does not 
support LU-LU verification level security, the application 
subsystem should set this parameter to all 1s 
(X’FFFFFFFF’). 


MAX _TPS specifies the maximum number of transaction 
programs that APPC/PC can run under this LU. If you 
try to initiate a transaction program when this maximum 
number has already been reached, APPC/PC rejects 
incoming ALLOCATEs and TP_STARTED verbs. 


QUEUE_ALLOCATES applies only if the application 
subsystem specified synchronous management of incoming 
ALLOCATEs (QUEUE_ALLOCATES = YES with the 
ATTACH_LU verb). 


e STOP specifies that APPC/PC should stop queueing 
incoming ALLOCATEs, and reject the already queued 
ALLOCATEs. 


e RESUME specifies that APPC/PC should resume 
queueing incoming ALLOCATEs. 


Returned Parameters: 


RETURN_CODE indicates whether the verb is 
acceptable (0) or not acceptable (non-0). If the verb is not 
acceptable, APPC/PC does not change any part of the 
local LU definition. See Appendix C, “Verb Return 
Codes,” for more information on return codes. The 


CHANGE_LU return codes are as follows: 
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e BAD _ LU_ID: APPC/PC does not recognize the 
specified LU_ID. 


e INVALID CHANGE: The application subsystem has 
made an invalid change in the management of 
incoming ALLOCATEs. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3, and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 
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CNOS (Change Number of Sessions) 


Establishes the initial mode session limit for single- or 
parallel-session connections. You also use the CNOS verb 
to reset the limit to 0. 


The CNOS verb defines a protocol boundary for use by 
programs that perform LU control functions. 


Before the detailed description of the CNOS verb is a 
discussion of LU-LU sessions and return codes, as well as 
a summary of the functions that APPC/PC supports. 


Understanding LU-LU Session 
Characteristics 


The two characteristics of LU-LU sessions that affect the 
CNOS verb are: 


e The method of connecting the LUs—single session or 
parallel sessions 


e The contention-winner polarities of LU-LU 
sessions—which LU has priority over the other LU. 


A connection between two LUs can be either single or 
parallel but not both. 


For single session connections, APPC/PC limits the 
number of active sessions between the two LUs to one. 
That is, an LU cannot activate another session until it 
deactivates the active session. 


The value of the PARTNER _LU_SESSION_LIMIT 
parameter of the ATTACH_LU verb implicitly specifies 
parallel- or single-session support. 


For parallel-session connections, the application 
subsystem can group sessions by mode names. A CNOS 
verb issued by either side causes the corresponding LUs to 
negotiate a limit for the number of active sessions for the 
specified mode name group. Additional sessions within 
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the mode name group can then be activated up to this 
negotiated limit. 


Relating the Mode Name to Network Properties 


Each single session or group of parallel sessions has 
associated with it a set of similar network properties and 
a mode name that identifies this set of network properties. 
Transaction programs use the mode name to select the set 
of network properties it wants to use for a conversation. 


The network properties grouped under a single mode name 
include, for example, the highest synchronization level for 
conversations on the sessions, the class of service for the 
sessions, and the session routing and delay 

characteristics. The correlation of mode names to the sets 
of network properties is established at system-definition 
time by the administrator of the network. 


Understanding Contention-Winner Polarity 


The contention-winner polarity for a session (single or 
parallel) indicates which of the corresponding LUs has 
priority when both LUs try to allocate a conversation on 
the session at the same time. For each single or parallel 
LU-LU session, only one LU is the contention winner of 
the session. The other LU is the contention loser of the 
session. 


The contention-winner LU can allocate a conversation on 
a session without requesting permission from the 
contention-loser LU. Conversely, the contention-loser LU 
must request permission from the contention-winner LU to 
allocate a conversation on the session. The 
contention-winner LU either grants or rejects the request. 
The two LUs establish contention-winner polarity of a 
session when they request APPC/PC to activate a session. 


For single sessions, the LU starting the session can 


request that it be the contention winner or loser. The LU 
responding to the session activation can accept the 


5-24 CNOS (Change Number of Sessions) 


requested polarity or change the polarity, depending on 
the requested polarity. 


If the initiating LU requests that it be the contention 
winner, the responding LU can accept the polarity or 
change the polarity making the responding LU the 
contention winner. If the initiating LU requests that it be 
the contention loser, the responding LU always accepts 
the contention-winner polarity. 


For parallel sessions, you can further divide each 
mode-name group of sessions based on contention-winner 
polarities. You can designate the minimum number of 
contention-winner sessions for one LU, and all or part of 
the remaining sessions as the minimum number of 
contention-winner sessions for the other LU. This 
partitioning enables two LUs to divide a group of parallel 
sessions between them to ensure that each LU becomes 
the contention winner of a minimum number of the 
sessions. 


The LU activating a parallel session can request that it be 
the contention winner or contention loser. The initiating 
LU can become the contention winner of a parallel 
session only if making the initiating LU the contention 
winner does not infringe on the partner LU’s minimum 
number of contention winners. Otherwise, the initiating 
LU becomes the contention loser. The LU responding to 
the activation of a parallel session always accepts the 
initiating LU’s choice of polarity. 


Changing the Mode Session Limit 


CNOS changes the session limit for a mode group of a 
given partner LU. This limit is called the mode session 
limit. APPC/PC uses this limit to restrict the number of 
LU-LU sessions per mode name that are available between 
two LUs for allocation to conversations. You can use 
CNOS to change the session limits for both single- and 
parallel-session connections. 
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For single sessions, CNOS changes the mode session limit 
only at the local LU. The remote LU does not take part 
in processing the change. 


For parallel sessions, a CNOS verb issued by either 
partner changes the mode session limits as well as other 
CNOS parameters of both LUs. These other CNOS 
parameters control the minimum number of 
contention-winner sessions for each LU: 


e Which LU is responsible for selecting and deactivating 
LU-LU sessions when you reset the mode session limit 


e Whether or not the LU drains allocation requests 
when you reset the mode session limits. 


If you issue a CNOS verb and parallel session support is 
specified, APPC/PC initiates and manages a conversation 
in order to perform negotiation between the two LUs. 
APPC/PC allocates this conversation on a session with 
the SNA-defined mode name, SNASVCMG. Therefore, 
you must first issue a CNOS verb for the SNASVCMG 


mode to increase the session limit. 


The LU that sends the CNOS request is referred to as the 
source LU; the LU that receives the CNOS request is 
referred to as the target LU. Two LUs executing a CNOS 
verb are considered a CNOS transaction. The role of the 
LU as a source LU or target LU lasts for the duration of 
the CNOS transaction. After either side issues the CNOS 
verb, APPC/PC assumes responsibility for creating and 
managing the CNOS transaction. 
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Understanding the CNOS Verb 


You must issue this verb to set the mode session limit for 
either parallel- or single-session connections for a 
partner-LU/mode name combination before a transaction 
program issues the first ALLOCATE for that destination. 
Otherwise, the ALLOCATE fails 

(ALLOC_FAIL NO_RETRY). 


When setting limits for a parallel session connection, the 
two LUs negotiate the mode session limits, drain settings, 
and responsibility values. APPC/PC updates these 
parameters in the CNOS command to reflect the settings 
agreed to by both LUs during negotiation. The 
application subsystem can issue the DISPLAY verb to 
obtain the negotiated mode session limit values. 


No CNOS negotiation occurs when setting the limits for 
single sessions (that is, the two LUs do not negotiate 
drain settings or responsibility values). Therefore, you 
must use another method to coordinate the CNOS 
parameter settings between partner LUs using a 
single-session connection. 


As part of setting up the initial limits, CNOS also sets the 
guaranteed (that is, the minimum) number of 
contention-winner polarities and contention-loser 
polarities, as well as setting initial activation counts for 
both polarities. The action of the CNOS verb normally 
affects only the group of sessions with the specified mode 
name between the source LU and the target LU. 
Alternately, with one CNOS command, you can reset the 
session limits of all modes for a partner LU to 0. 


APPC/PC enforces the new mode session limit and 
contention-winner polarity maximums until one side or 
the other changes them by issuing a subsequent CNOS 
verb. However, the partner LU may issue the subsequent 
CNOS verb, which could mean that the request is 
invisible at the source API. 


After the CNOS verb raises the session limit above 0, it 
can only reset the limit to 0. It cannot set the session 


CNOS (Change Number of Sessions) 5-27 


limit to a different non-0 value, and it can not redistribute 
the number of sessions allocated as the contention 
winners and losers. Therefore, you cannot change the 
-mode session limits if the partner LU has already set the 
limits to a non-0 value. 


APPC/PC may activate one or more LU-LU sessions with 
the specified mode name as a result of initializing the 
session limit. APPC/PC terminates all LU-LU sessions for 
the specified mode name (or for all mode names) as a 
result of resetting the session limit to 0. APPC/PC 
terminates each session as it becomes free and does not 
interrupt active conversations. 


The application subsystem can specify the session limit for 
use in CNOS negotiations when defining the local LU 
using the ATTACH_LU verb (see “ATTACH LU” on 
page 5-7). You can make this limit higher than the 
current session limit to handle potential requests from the 
partner LU for a higher session limit. 


You can redefine the mode session limit (but not the local 
LU session limit or the partner LU session limit) using the 
CNOS verb. Ifthe SET NEGOTIABLE parameter value is 
YES, the corresponding value given in this CNOS verb 
overrides the 

MODE MAX NEGOTIABLE _SESSION_LIMIT value 
from the ATTACH _LU verb. 


5-28 CNOS (Change Number of Sessions) 


Supplied Parameters: 
LU_ID (variable) 
PARTNER_LU_NAME (variable) 
MODE_NAME SELECT (ALL) 
(ONE, 'SNASVCMG' ) 
(ONE, variable) 


SET_NEGOTIABLE (NO) 
(YES) 


PARTNER_LU_MODE_SESSION_LIMIT (variable) 
MIN_CONWINNERS_SOURCE (variable) 
MIN _CONWINNERS_ TARGET (variable) 


AUTO_ACTIVATE (variable) 


RESPONSIBLE (SOURCE) 
(TARGET) 


DRAIN _SOURCE (NO) 
(YES) 


DRAIN_TARGET (NO) 
(YES) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


LU_ID specifies the identifier for the local LU for which 
you are issuing this CNOS verb. APPC/PC returns this 
value when the application subsystem defines the LU with 
the ATTACH LU verb. For more information on 
ATTACH_LU, see “ATTACH LU” on page 5-7. 


PARTNER_LU_NAME specifies the name of the target 


LU for which the initialization of session limits and 
polarities applies. 
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MODE_NAME_ SELECT specifies the mode name for 
which you are setting or resetting the session limits and 
polarities. 


e ALL specifies that the CNOS verb is to change the 
session limits and polarities for all mode names that 
apply to the target LU. The single mode name that 
CNOS does not change when you specify ALL is the 
SNA-defined mode name, SNASVCMG. You can use 
the ALL setting for MODE_ NAME_ SELECT only 
when resetting session limits to 0. 


e ONE, ‘SNASVCMG’ specifies the SNA-defined mode 
name (in EBCDIC). This mode is only for use by a 
CNOS transaction when the source LU and target LU 
are using parallel sessions. 


e ONE, variable (where variable represents a mode 
name) specifies changes to the session limit and 
polarities for only the specified mode name. 


SET_NEGOTIABLE specifies whether APPC/PC also 
uses the PARTNER _LU_MODE_SESSION_LIMIT 
specified in the CNOS verb to override the current 
settings for 

MODE MAX NEGOTIABLE SESSION_LIMIT. The 
application subsystem sets this limit first in the 
ATTACH_LU verb but a later CNOS verb, with the 
SET_NEGOTIABLE parameter equal to YES, can 
override this value. When you specify 
SET_NEGOTIABLE (YES), a normal CNOS negotiation 
still takes place. If the CNOS verb contains no parameter 
errors, the new local negotiation values take effect, even 
if the partner LU (in the parallel-session case) negotiates 
the suggested values down. 


PARTNER_LU_MODE_SESSION_LIMIT specifies the 
mode session limit for parallel-session connections. That 
is, it specifies the maximum number of parallel sessions 
allowed between the source LU and target LU, for the 
group of sessions under the specified mode name. 
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If the mode session limit is currently greater than 0, the 
value of this parameter must be 0. That is, the CNOS 
verb can raise the limit above 0, but the next CNOS verb 
must set the value to 0; you cannot change the mode 
session limit from one non-0 number to another. 


When raising the mode session limit above 0, the target 
LU can negotiate this parameter to a value greater than 0 
and less than the specified session limit. The specified 
session limit, or the negotiated session limit if it is 
negotiated, becomes the new mode session limit. 


The value specified for this parameter must be greater 
than or equal to the sum of the values specified on the 
CNOS MIN_CONWINNERS_SOURCE and 
MIN _CONWINNERS_ TARGET parameters. 


For single-session connections, the value of this parameter 
must not be greater than 1. 


For the SNASVCMG mode name, the specified mode 
session limit must be 0, 1, or 2. The specified limit 
depends on whether you are preparing the SNASVCMG 
mode for more CNOS commands (one or two) or you are 
shutting down the mode (0). 


If the ATTACH_PU verb specifies 
RETURN_CONTROL(IINCOMPLETE), the mode session 
limit should be large enough to accommodate all active 
conversations on the mode for any one transaction 
program. If the ATTACH_PU verb specifies 
RETURN_CONTROL(COMPLETE), the mode session 
limit should be large enough to accommodate all active 
conversations on the mode for all transaction programs. 


MIN _CONWINNERS_SOURCE specifies the minimum 
number of sessions of which the source LU is guaranteed 
to be the contention winner. The specified number must 
be 0 or greater. The specified number, or the negotiated 
number, becomes the new minimum number of 
contention-winner sessions for the source LU. The sum of 
this number and the target LU’s new minimum number of 
contention-winner sessions cannot exceed the new session 
limit. 
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When the specified number is greater than half the new 
session limit (rounded up), the target LU can negotiate 
this parameter down to half the new session limit. When 
the specified number is less than or equal to half the new 
session limit, the target LU cannot negotiate this 
parameter. 


For single-session connections, this parameter specifies 
the desired contention-winner polarity of the session for 
the source LU. 


For the SNASVCMG mode name with a mode session 
limit of 2, the specified minimum number of 
contention-winner sessions for the source LU must be 1. 
For the SNASVCMG mode name with a mode session 
limit of 1, the specified minimum number of 
contention-winner sessions for the source LU must be 0. 


This parameter is valid only when the application 
subsystem is setting the session limit to a non-0 value. 


The target LU may negotiate this value for a 
parallel-session connection; APPC/PC returns the new 
value to the calling program in this parameter. 


MIN CONWINNERS_TARGET specifies the minimum 
number of sessions of which the target LU is guaranteed 
to be the contention winner. The specified number must 
be 0 or greater. The specified number, or the negotiated 
number if it is negotiated, becomes the new minimum 
number of contention-winner sessions for the target LU. 
The sum of this number and the source LU’s new 
minimum number of contention-winner sessions cannot 
exceed the new session limit. 


The target LU can negotiate this parameter to a number 
less than or equal to the new session limit minus the new 
minimum number of contention-winner sessions for the 
source LU. 


For single-session connections, this parameter specifies 
the desired contention-winner polarity for the target LU. 
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For the SNASVCMG mode name, the specified minimum 
number of contention-winner sessions for the target LU 
must be 1. 


This parameter is valid only when the application 
subsystem is setting the mode session limit to a non-0 
value. 


AUTO_ACTIVATE specifies the number of 
contention-winner sessions for APPC/PC to activate 
automatically, rather than by allocation requests from the 
transaction program. 


Warning: Do not specify AUTO_ACTIVATE if the Link 
Take-Down option for an SDLC switched line was 
specified on the APPC/PC configuration menu that sets 
the parameters for SDLC operation. Specifying both Link 
Take-Down and AUTO_ACTIVATE can cause thrashing 
when APPC/PC attempts to activate sessions until the 
AUTO_ACTIVATE limit is reached. 


This parameter is valid only when the application 
subsystem is setting the mode session limit to a non-0 
value. If the parameter is greater than the 

MIN _CONWINNERS_ SOURCE parameter (after any 
negotiation in the parallel-session connection case), 
APPC/PC decreases the parameter to the negotiated 
value. 


On a busy IBM Token-Ring Network, this parameter may 
conflict with the congestion algorithm that APPC/PC uses 
to terminate unused sessions and links when congestion 
rises past a certain threshold. Auto-activation by either 
peer partner may re-establish sessions and links, possibly 
resulting in a thrashing situation. Therefore, the 
application subsystem should not specify auto-activation 
between peer nodes for a large congested network. The 
congestion algorithm does not apply to a host connection, 
and you can specify auto-activation for sessions to an 
SNA network, using a boundary function. 


RESPONSIBLE, DRAIN SOURCE, and 
DRAIN_TARGET are session-terminating control 
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parameters. These parameters are valid only when using 
CNOS to set the mode session limit to 0. 


RESPONSIBLE specifies which LU is responsible for 
deactivating the sessions as a result of resetting the 
session limit for parallel-session connections. This 
parameter does not apply to single-session connections or 
the SNASVCMG sessions. The target LU may negotiate 
this value. 


e SOURCE specifies that the source LU is responsible. 
The target LU cannot negotiate this specification. 


e TARGET specifies that the target LU is responsible. 
The target LU can negotiate this specification to 
SOURCE, in which case the source LU becomes 
responsible. 


Whether an LU deactivates a session immediately after 
the current conversation or after all queued conversations 
are complete depends on the DRAIN SOURCE and 
DRAIN_TARGET parameters. 


e If an LU is to drain its allocation requests, it 
continues to allocate conversations to active sessions. 
The responsible LU deactivates a session only when 
the conversation allocated to the session is deallocated 
and no request is waiting for allocation to any session 
with the specified mode name. The allocation of a 
waiting request takes precedence over the deactivation 
of a session. 


e If an LU is not to drain its allocation requests, the 
responsible LU deactivates a session as soon as the 
conversation allocated to the session is deallocated. If 
no conversation is allocated to the session, the 
responsible LU deactivates the session immediately. 


However, this verb cannot force deallocation of active 
conversations. 


The RESPONSIBLE and MODE_NAME_ SELECT 
parameters are interrelated as follows: 
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e APPC/PC ignores the RESPONSIBLE parameter for 
mode names for which the session limit is currently 0 
if the application subsystem specifies 
MODE_NAME_SELECT(ALL). 


e If the application subsystem specifies 
MODE NAME _ SELECT(ONE, variable) with a 
session limit of 0 and the current session limit for that 
mode name is already 0, the RESPONSIBLE parameter 
must specify the same LU (source or target) as is 
currently responsible for deactivating sessions. You 
can use this procedure to change the DRAIN option 
specified in an earlier CNOS command. 


DRAIN_SOURCE specifies whether the source LU can 
drain its allocation requests. For parallel-session 
connections, the target LU cannot negotiate this 


parameter. This parameter does not apply to the 
SNASVCMG sessions. 


e NO specifies that the source LU cannot drain its 
allocation requests. APPC/PC rejects all requests 
currently waiting for allocation, or subsequently 
issued requests, at the source LU and issues a return 
code of ALLOCATION_ERROR. 


e YES specifies that the source LU can drain its 
allocation requests. The source LU continues to 
allocate conversations to the sessions until no requests 
are waiting for allocation, at which time its draining is 
ended. APPC/PC rejects all allocation requests issued 
at the source LU with a return code of 
ALLOCATION_ERROR. 


For parallel-session connections, the DRAIN_ SOURCE 
and MODE_NAME_SELECT parameters are interrelated, 
as follows: 


e Ifthe application subsystem specifies 
MODE_NAME_ SELECT(ALL) and 
DRAIN _SOURCE(YES), APPC/PC ignores the 
DRAIN _SOURCE parameter for those mode names for 


which the session limit is currently 0. 
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If the application subsystem specifies 

MODE NAME _ SELECT(ALL) and 

DRAIN _SOURCE(NO), APPC/PC accepts the 
DRAIN SOURCE parameter for all mode names. 
APPC/PC terminates draining for any mode currently 
draining its requests. 


If the application subsystem specifies 

MODE NAME_SELECT (ONE, variable) and 
DRAIN _SOURCKE(YES) is currently in effect, 
DRAIN_SOURCE(NO) directs APPC/PC to terminate 
the draining of the source LU. 


If the application subsystem specifies 

MODE _NAME_SELECT(ONE, variable) and 
DRAIN SOURCE(NO) is currently in effect, the 
application subsystem must specify 

DRAIN _SOURCE(NO) again. 


DRAIN_ TARGET specifies whether the target LU can 
drain its allocation requests. This parameter does not 
apply to the SNASVCMG sessions. 


For a parallel-session connection, the partner LU may 
negotiate this value; APPC/PC returns the new value to 
the calling program in this parameter. 


NO specifies that the target LU cannot drain its 
allocation requests. Requests currently waiting for 
allocation, or issued later at the target LU, will be 
rejected. The target LU cannot negotiate this 
specification for parallel-session connections. 


YES specifies that the target LU can drain its 
allocation requests. The target LU continues to 
allocate conversations to the sessions until no requests 
are waiting for allocation, at which time its draining is 
ended. Allocation requests issued at the target LU 
after draining ends are rejected. For parallel-session 
connections, the target LU can negotiate this 
specification to NO, in which case the target LU 
cannot drain its allocation requests. 
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For parallel-session connections, this parameter and 
MODE_NAME_ SELECT are interrelated, as follows: 


If the application subsystem specifies 
MODE_NAME_SELECT(ALL) and 
DRAIN_TARGET(YES), APPC/PC ignores the 
DRAIN_TARGET parameter for the mode names for 
which the session limit is currently 0. 


If the application subsystem specifies 
MODE_NAME_SELECT(ALL) and 
DRAIN_TARGET(NO), APPC/PC accepts the 
DRAIN_TARGET parameter for all mode names, 
regardless of the current session limit. Any draining 
of allocation requests at the target LU is terminated. 


If the application subsystem specifies 

MODE _NAME_SELECT(ONE, variable) and 
DRAIN_TARGET(YES) is currently in effect, 
DRAIN_TARGET(NO) terminates the target LU’s 
draining. 


If the application subsystem specifies 
MODE_NAME_SELECT(ONE,variable) and 
DRAIN_TARGET(NO) is currently in effect, the target 
LU can either accept the DRAIN_TARGET(YES) 
parameter or negotiate the parameter to NO. After the 
target LU accepts the DRAIN _TARGET(YES) 
parameter, it can drain any remaining allocation 
requests. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
It consists of a 2-byte “primary” code and a 4-byte 
“secondary” code. See Appendix C, “Verb Return Codes,” 
for more information on return codes. The CNOS return 
codes are as follows: 


OK: Indicates that APPC/PC executed the CNOS verb 
successfully. 
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The following secondary codes indicate whether 
APPC/PC accepts the parameters as specified in the 
CNOS verb or as negotiated by the partner LU. 


— CNOS_ACCEPTED: APPC/PC accepts the session 
limits and responsibility as specified. 


— CNOS_NEGOTIATED: APPC/PC accepts the 
session limits and responsibility as negotiated by 
the partner LU. 


e PARAMETER CHECK 


— BAD_LU_ID: APPC/PC does not recognize the 
value specified for the LU_ID parameter. 


— ALL MODE MUST_RESET: APPC/PC does not 
permit the specification of a non-0 session limit 
when MODE_NAME_SELECT indicates ‘ALL’. 


— BAD _SNASVCMG_LIMITS: The application 
subsystem has specified invalid settings for the 
PARTNER _LU_MODE_SESSION_LIMIT, 
MIN_CONWINNERS_SOURCE, or 
MIN _CONWINNERS_ TARGET parameters when 
MODE_NAME(‘SNASVCMG’) is indicated. 


The three groups of valid settings are as follows: 


— PARTNER_LU_MODE_SESSION_LIMIT(2) 
MIN_CONWINNERS_SOURCE(1) 
MIN_CONWINNERS_TARGET(1) 


— PARTNER_LU_MODE_SESSION_LIMIT() 
MIN_CONWINNERS_SOURCE(0) 
MIN_CONWINNERS_TARGET(1) 


— PARTNER_LU_MODE_SESSION_LIMIT(0) 
MIN_CONWINNERS_SOURCE(0) 
MIN_CONWINNERS_TARGET(0) 


— MINS _GT_TOTAL: The sum of 


MIN CONWINNERS_ SOURCE and 
MIN _CONWINNERS_TARGET specifies a number 
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greater than 
PARTNER_LU_MODE_SESSION_ LIMIT. 


— MODE CLOSED: CNOS cannot set a non-0 limit 
because the local maximum negotiable session limit 
is currently 0 for the specified mode. 


—- BAD MODENAME: The specified partner LU 
does not support the specified mode name. 


— RESET_SNA_DRAINS: The SNASVCMG mode 
does not support the DRAIN settings. 


— SINGLE_NOT_SRC_RESP: For a single-session 
CNOS verb (for which an ATTACH _LU verb was 
issued with PARTNER _LU_SESSION_LIMIT = 
1), APPC/PC permits only the local (source) LU to 
be responsible for deactivating sessions. Set the 
RESPONSIBLE parameter to indicate the source 
LU. 


— BAD _PARTNER_LU: APPC/PC does not 
recognize the specified partner LU name. 


— EXCEEDS MAX ALLOWED: The local 
maximum negotiable session limit is less than the 
session limit specified with the CNOS verb. 


— CHANGE_SRC_DRAINS: APPC/PC does not 
permit you to specify 
MODE_NAME_SELECT(ONE) and 
DRAIN_SOURCE(YES) when 
DRAIN_SOURCK(NO) is currently in effect for the 
specified mode. 


ALLOCATION_ERROR 


— ALLOCATION _FAILURE_NO_RETRY: 
APPC/PC cannot allocate the conversation because 
of a permanent error condition. 


— ALLOCATION _FAILURE_RETRY: APPC/PC 
cannot allocate the conversation because of a 
temporary error condition. 
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e STATE_CHECK 


—- CANT_RAISE_ LIMITS: APPC/PC does not 
permit you to set session limits to a non-0 value 
unless the limits are currently 0. 


— LU_DETACHED: A DETACH _LU verb has reset 
the definition of the local LU before the CNOS 
verb tried to specify that LU. 


e CNOS_PARTNER_REJECT: The partner LU rejected 
a CNOS request from the local LU. 


— CNOS_MODE_ CLOSED: The local LU cannot 
negotiate a non-0 session limit because the local 
maximum session limit of the partner LU is 0. 


— CNOS_BAD MODENAME: The partner LU does 
not recognize the specified mode name. 


— CNOS_COMMAND_ RACE REJECT: APPC/PC 
is currently processing a CNOS verb issued by the 
partner LU. You should retry the CNOS command 
later. 


APPC/PC includes an internal CNOS service 
transaction program that executes CNOS verbs. While 
using some of the conversation verbs (ALLOCATE, 
SEND, RECEIVE _AND_ WAIT, and DEALLOCATE) 
to perform CNOS protocol, the CNOS service 
transaction program may receive any error return code 
defined for the conversation verb that it issued. In 
this case, the CNOS verb returns the received return 
code. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


e APPC_ABENDED 


e APPC_BUSY 
e APPC_DISABLED. 
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Notes (when setting session limits above 0): 


l. 


APPC/PC initializes the mode session limit for a 
single-session connection to a target LU only at the 
source LU; no CNOS transaction occurs. The mode 
session limit for the specified target LU and mode 
name must be initialized at both the source LU and 
target LU before either LU can activate the 
corresponding session. APPC/PC can then activate 
the session automatically after completing this verb, or 
in response to an allocation request. In this case, you 
may want to issue CNOS before you issue 


ACTIVATE_DLC. 


Initializing the SNASVCMG mode is the first step in 
setting up a parallel-session connection to a target LU. 
The application subsystem must issue the CNOS verb 
to initialize the mode session limit and 
contention-winner polarities for the SNASVCMG mode 
for a target LU before it can initialize any other mode 
for that target LU. The application subsystem issues 
the ATTACH_LU verb to define the target LU and 
issues the CNOS verb to enable a session with the 
SNASVCMG mode name. 


The mode session limit and contention-winner 
polarities for the SNASVCMG mode name must be 
initialized at both the source and target LUs before 
either LU can activate the corresponding sessions. 
APPC/PC can then activate the sessions automatically 
after completion of this verb, or in response to an 
allocation request. 


When initializing parallel-session limits, the CNOS 
verb operates on groups of sessions with the same 
mode name. The application subsystem uses the CNOS 
verb to initialize the limits on the number of active 
parallel sessions that can exist concurrently within a 
mode-name group between the source and target LUs. 
The limits imposed on the number of active parallel 
sessions within a mode-name group are: 


e The number of active sessions cannot exceed the 
mode session limit. 
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The number of active contention-winner sessions 
for the source LU cannot exceed the mode session 
limit minus the minimum number of 
contention-winner sessions for the target LU. 


The number of active contention-winner sessions 
for the target LU cannot exceed the mode session 
limit minus the new minimum number of 
contention-winner sessions for the source LU. 


5. When a CNOS verb specifies the AUTO_ACTIVATE 
option, the source LU will attempt to activate sessions 
to conform to the new limits. 


An LU can activate sessions in response to either a 
CNOS or an ALLOCATE verb according to the 
following conditions: 


If the minimum number of contention-winner 
sessions for the source LU is greater than 0, the 
source LU can activate contention-winner sessions 
up to this minimum number. 


If the sum of the minimum number of 
contention-winner sessions for both the source LU 
and the target LU is less than the mode session 
limit, both LUs can activate additional 
contention-winner sessions. APPC/PC provides 
these sessions on a first-come, first-served basis up 
to the new session limit. The LU can activate 
these sessions in response to ALLOCATE requests. 


An LU can activate additional contention-loser 
sessions up to the mode session limit when 
activating additional contention-winner sessions 
does not leave enough sessions to satisfy the 
minimum number of contention-winner sessions for 
the partner LU. The LU can activate these 
contention-loser sessions in response to 
ALLOCATE requests. 


Control may return to the user before APPC/PC 
finishes activating any automatically activated 
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sessions; that is, when APPC/PC has initiated, but 
not necessarily completed, the activation process. 


Notes (when setting session limits to 0): 


Ee 


Only the source LU can reset the mode session limit 
for a single-session connection to a target LU. In this 
case, a CNOS transaction does not occur. The source 
LU deactivates active sessions according to the 
DRAIN_SOURCE and DRAIN_TARGET parameters. 


The responsible LU deactivates the group of parallel 
sessions associated with a specified mode name (other 
than SNASVCMG) according to the DRAIN_ SOURCE 
and DRAIN_TARGET parameters. If the 

MODE _NAME_SELECT parameter specifies ALL, the 
responsible LU deactivates all sessions associated with 
all modes other than SNASVCMG. The application 
subsystem must reset the mode session limits and 
contention-winner polarities for all mode names other 
than SNASVCMG before issuing the CNOS verb with 
the SNASVCMG mode name specified. 


When the application subsystem resets the mode 
session limit and contention-winner polarities for 
parallel sessions associated with the SNA-defined mode 
name (SNASVCMG), APPC/PC resets these parameters 
only at the source LU. A CNOS transaction does not 
occur. The source LU deactivates the sessions 
associated with the SNASVCMG mode name as soon 
as all other active sessions between the source LU and 
target LU are deactivated. If no other sessions 
between the two LUs are active, the source LU 
immediately deactivates the sessions associated with 


the SNASVCMG mode name. 


Control may return to the program that issues the 

CNOS verb before the LU finishes deactivating the 
session; that is, when the deactivation process has 

started but not necessarily completed. 


You must specify the PARTNER _LU_NAME and the 
mode name (including SNASVCMG) in EBCDIC. You 
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can use the CONVERT verb to convert these 
parameters from ASCII to EBCDIC. 
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DETACH_LU 


Terminates a local LU. Transaction programs must not be 
using any sessions or conversations attached to this local 
LU when you issue this verb. You must make sure that 
all sessions between the named local LU and the partner 
LUs are first terminated by issuing a previous CNOS verb 
that sets session limits to 0. After DETACH _ LU, 
APPC/PC does not accept incoming session activation 
requests for the local LU. Also, APPC/PC will not honor 
locally issued verbs (such as ALLOCATE) for the specified 
local LU (that is, the previously assigned LU_ID from 
ATTACH _LWU is now invalid). 


Supplied Parameters: 
DETACH _LU LU_ID (variable) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


LU_ID specifies the identifier for the local LU you want 
to deactivate. APPC/PC returned this value when 
ATTACH _LU identified and initialized the LU. For more 
information, see “ATTACH _LU” on page 5-7. 


If a transaction program issues DETACH _LU before all 
conversations and sessions for the LU are terminated, a 
deadlock may occur because the sessions may never be 
terminated. 


The application subsystem may issue DETACH_LU only 


for an independent LU, that is, an LU that is notina 
session with an SNA host SSCP. 


Returned Parameters: 
RETURN_CODE indicates the result of APPC/PC’s 


execution of the DETACH LU verb. See 
Appendix C, “Verb Return Codes,” for more information 
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on return codes. The DETACH _LU return codes are as 
follows: 


e BAD LU_ID: APPC/PC does not recognize the 
specified LU_ID. 


e SSCP CONNECTED LU: The LU is in a session 
with an SNA host System Services Control Point 
(SSCP). Peer-to-peer sessions have been deactivated 
but the LU has not been terminated. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3, and Appendix C, “Verb Return Codes.” 


e APPC ABENDED 
e APPC BUSY 

e APPC DISABLED 
e OK. 

Note: 


APPC/PC terminates all transaction programs still 
attached to the local LU (that is, APPC/PC generates 
TP_ENDED automatically). 
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DETACH PU 


Terminates the local PU. If any LUs are active (not 
DETACHed), APPC/PC deactivates them through an 
implicit (internal) invocation of DETACH LU. For 
DETACH_PU(TYPE=SOFT), the rules for detaching 
sessions and local transaction programs associated with 
the LUs are the same as for DETACH LU. 


DETACH_PU also deactivates the link-level connections 
for the IBM PC. If you continue issuing verbs, you must 
first issue the ATTACH PU, ATTACH LU, and 
ACTIVATE_DLC verbs to re-open the communication 
adapters. 


APPC/PC returns control to the program issuing the verb 
after it terminates all resources of the node. 


Supplied Parameters: 


DETACH _PU TYPE (HARD) 
(SOFT) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TYPE specifies whether APPC/PC should terminate the 
sessions and conversations associated with the LUs 
immediately or after the transaction programs terminate 
their conversations. 


e HARD directs APPC/PC to stop the sessions and 
conversations immediately, without waiting for the 
transaction programs to terminate the sessions and 
conversations normally. The HARD option may cause 
APPC/PC to send network management error messages 
to a network manager (if there is a session with the 
SSCP at the host). You can use this option when the 
program is “hung” and the user presses the Ctrl-Break 
key (for more information see Chapter 2, “Developing 
an Application Subsystem”). 
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SOFT directs APPC/PC to wait for the transaction 
programs to terminate their conversations. After all 
conversations are terminated, APPC/PC terminates the 
sessions those conversations were using. 


Returned Parameters: 


RETURN_CODE indicates the result of APPC/PC’s 
execution of the DETACH PU verb. See 

Appendix C, “Verb Return Codes,” for more information 
on return codes. The DETACH PU return codes are as 
follows: 


NO_PU_ ATTACHED: The application subsystem has 
not yet issued ATTACH _PU to define the PU being 
detached. 


ADAPTER CLOSE FAILURE: APPC/PC has 
experienced a failure while trying to close an adapter. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


e APPC_ABENDED 

e APPC_BUSY 

e APPC_DISABLED 

e OK. 

Notes: 

1. The application subsystem can gain control at an 


interrupt and then issue DETACH PU 

(TYPE =HARD) while APPC/PC is processing a 
conversation verb. In this case, DETACH PU 
overrides the current verb, and APPC/PC returns 
control to the point at which the application 
subsystem issued DETACH PU. 


You may also issue DETACH PU (TYPE= HARD) 
after APPC/PC has abnormally terminated to shut 

down the adapter. This action may not succeed for 
some kinds of abnormal termination. 
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DETACH_PU (TYPE=HARD) is the only control or 
transaction verb that APPC/PC will process while it is 
executing another verb. 


A short delay may occur after issuing the 


DETACH_PU verb before the SDLC adapter shuts 
down. 
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DISPLAY 


Returns the current operating parameter values that 
control the operation of the local LU. DISPLAY does not 
cause any information to flow outside the local LU; it 
reads information from the local LU only. 


DISPLAY 


Supplied Parameters: 
LU_ID (variable) 
PARTNER_LU_NAME (variable) 


MODE_NAME (variable) 
Returned Parameters: 


RETURN_CODE (variable) 
LU_SESSION_LIMIT (variable) 
PARTNER_LU_SESSION_ LIMIT (variable) 


MODE_MAX NEGOTIABLE _SESSION_LIMIT 
(variable) 


CURRENT_SESSION_LIMIT (variable) 
MIN_NEGOTIATED_WINNER_LIMIT (variable) 
MIN_NEGOTIATED_LOSER_LIMIT (variable) 
ACTIVE_SESSION_COUNT (variable) 


ACTIVE_CONWINNER_SESSION_COUNT 
(variable) 


ACTIVE_CONLOSER_SESSION_COUNT (variable) 
SESSION_TERMINATION_COUNT (variable) 


SESSION_TERMINATION_SOURCE_DRAIN (NO) 
(YES) 


SESSION_TERMINATION_TARGET_DRAIN (NO) 
(YES) 
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Supplied Parameters: 


LU_ID specifies the identifier for the local LU for which 
APPC/PC is to retrieve operating parameters. APPC/PC 
returns the LU_ID value when the application subsystem 
defines the LU with the ATTACH _LU verb. (For more 
information, see “ATTACH LU” on page 5-7.) 


PARTNER _LU_NAME specifies the name of the remote 
LU for which DISPLAY is to retrieve operating 
parameters. 


MODE_NAME specifies the name of the mode for which 
DISPLAY is to retrieve operating parameters. 


Returned Parameters: 


RETURN_CODE indicates whether the verb is 
acceptable (0) or not acceptable (non-0). See 

Appendix C, “Verb Return Codes,” for more information 
on return codes. The DISPLAY return codes are as 
follows: 


e BAD _LU_ID: APPC/PC does not recognize the 
supplied LU_ID parameter value. 


e BAD PART LUNAME: APPC/PC does not recognize 
the supplied PARTNER _LU_NAME parameter value. 


e BAD MODENAME: APPC/PC does not recognize the 
supplied MODE_NAME parameter value. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 
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LU_SESSION_LIMIT returns the maximum number of 
sessions permissible for the local LU, as specified in 
ATTACH LU. (For more information, see 

“ATTACH LU” on page 5-7.) 


PARTNER LU _SESSION_LIMIT returns the 
maximum number of sessions permissible between the 
local LU and the partner LU, as specified in 
ATTACH LU. (For more information, see 
“ATTACH LU” on page 5-7.) 


MODE_MAX NEGOTIABLE_SESSION_LIMIT 
returns the maximum number of sessions permissible 
between the local LU and the partner LU for the 
designated mode name, as specified in ATTACH _LU or 
altered by a CNOS transaction. For more information, see 
“ATTACH LU” on page 5-7.) 


CURRENT_SESSION_LIMIT returns the currently 
agreed-upon maximum session limit between the local LU 
and the partner LU for the designated mode name (as 
specified or negotiated by executing a CNOS verb). 


MIN NEGOTIATED _ WINNER_LIMIT returns the 
minimum number of contention-winner sessions 
permissible between the local LU and the partner LU for 
the designated mode name (as specified or negotiated by 
executing a CNOS verb). 


MIN NEGOTIATED _LOSER_LIMIT returns the 
minimum number of contention-loser sessions permissible 
between the local LU and the partner LU for the 
designated mode name (as specified or negotiated by 
executing a CNOS verb). 


ACTIVE SESSION_COUNT returns the number of 
currently active sessions between the local LU and the 
partner LU for the designated mode name. 


ACTIVE_CONWINNER_SESSION_COUNT returns 
the number of currently active contention-winner sessions 
between the local LU and the partner LU for the 
designated mode name. 
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ACTIVE _CONLOSER_SESSION_COUNT returns the 
number of currently active contention loser sessions 
between the local LU and the partner LU for the 
designated mode name. 


SESSION_TERMINATION_COUNT returns the 
number of currently active sessions that the local LU is 
responsible for terminating (as the result of a previous 


CNOS verb). 


SESSION_TERMINATION_SOURCE_DRAIN 
indicates whether the local LU drains the queue of 
ALLOCATE requests before terminating sessions in 
response to a CNOS verb issued by either side. For more 
information, see “Understanding the CNOS Verb” on 
page 5-27. 


SESSION_TERMINATION_TARGET_ DRAIN 
indicates whether the remote LU drains the queue of 
ALLOCATE requests before terminating sessions as a 
result of a CNOS verb. For more information, see 
“Understanding the CNOS Verb” on page 5-27. 


Note: 
You must specify the PARTNER _LU_ NAME and 


MODE _ NAME in EBCDIC. You can use the CONVERT 
verb to convert these parameters from ASCII to EBCDIC. 
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GET_ALLOCATE 


Requests APPC/PC to dequeue the next queued incoming 
ALLOCATE if you have specified synchronous 
management of incoming ALLOCATEs. 


Alternatively, the application subsystem can test for 
queued ALLOCATEs, without dequeuing one. 


In both cases, APPC/PC supplies a return code of OK if 
the queue holds an incoming ALLOCATE, and a return 
code of UNSUCCESSFUL if the queue does not hold an 
incoming ALLOCATE. 


The application subsystem should issue the 
GET_ALLOCATE verb only if it specified synchronous 
management of incoming ALLOCATEs 
(QUEUE_ALLOCATES = YES in the ATTACH_LU verb). 


Supplied Parameters: 
GET_ALLOCATE LU_ID (variable) 


TYPE (DEQUEUE) 
(TEST 


) 


Returned Parameters: 
RETURN_CODE (variable) 


CREATE TP _ PTR (variable) 


Supplied Parameters: 


LU_ID specifies the identifier for the local LU that the 
application subsystem wants to access. APPC/PC returns 
this value when the application subsystem identifies and 
initializes the LU by issuing the ATTACH_LU verb. For 
more information, see “ATTACH LU” on page 5-7. 


TYPE specifies whether APPC/PC is to dequeue a queued 


incoming ALLOCATE or only test for the presence of an 
incoming ALLOCATE in the queue. 
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Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
See Appendix C, “Verb Return Codes,” for more 
information on return codes. The GET ALLOCATE 
return codes are as follows: 


e BAD LU_ID: APPC/PC does not recognize the 
specified LU_ID. 


e GET _ALLOC_BAD_TYPE: APPC/PC does not 
recognize the parameter specified in the TYPE field. 


e UNSUCCESSFUL: The LU is not currently holding 
any incoming ALLOCATKEs in its queue. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


CREATE_TP_PTR specifies a pointer to a CREATE_TP 
record identical in format to the record APPC/PC passes 
to the user exit for incoming ALLOCATEs when you use 
asynchronous management of incoming allocates. This 
record contains the TP_ID and CONV_ID of the new 
transaction program and the new conversation. 
CREATE_TP_ PTR is set only if TYPE = DEQUEUE and 
RETURN_CODE=OK. For more information see 
“CREATE TP” on page 5-66. 
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TP_ENDED 


Notifies APPC/PC of the end of the identified transaction 
program. APPC/PC responds by performing a 
DEALLOCATE (TYPE= ABEND_ PROG) to free only 
conversations associated with that program. For more 
information, see “DEALLOCATE” on page 7-32. 


Supplied Parameters: 
TP ENDED TP_ID (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
that you want to terminate. APPC/PC returns this value 
when the application subsystem initiates the program with 
the TP_STARTED verb (see “TP_STARTED” on 

page 5-58) or with the CREATE_ TP verb (see 
“CREATE _ TP” on page 5-66). 


Returned Parameters: 


RETURN_CODE indicates whether APPC/PC accepts 
the TP_ENDED request. See Appendix C, “Verb Return 
Codes,” for more information on return codes. The 

TP _ENDED return codes are as follows: 


e BAD_TP_ID: APPC/PC does not recognize the 
supplied TP ID as an assigned transaction program 


ID. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3, and Appendix C, “Verb Return Codes.” 


e APPC_ABENDED 
APPC_BUSY 
e APPC_DISABLED 
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e INCOMPLETE (possible only if all conversations are 
not deallocated) 
e OK. 


Note: 
After the application subsystem issues TP_ENDED, the 


TP_ID is no longer a legal value for any basic or mapped 
conversation verb. 
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TP_STARTED 


Notifies APPC/PC that the application subsystem has 
requested resources for a transaction program initiated as 
a result of a local command, rather than initiated from an 
incoming ALLOCATE. APPC/PC responds by generating 
a transaction program identifier (TP_ID) and returning it 
to the application subsystem. The initiated transaction 
program must use this TP_ID with all later conversation 
verbs. 


Supplied Parameters: 


TP_STARTED LU_ID (variable) 
Returned Parameters: 


TP_ID (variable) 


RETURN_CODE (variable) 


Supplied Parameters: 


LU_ID specifies the identifier for the local LU under 
which the application subsystem wants to initiate this 
transaction program. APPC/PC returns this value when 
the application subsystem identifies and initializes the LU 
by issuing the ATTACH _LU verb; see “ATTACH LU” on 
page 5-7. 


Returned Parameters: 


TP_ID specifies the identifier for this transaction 
program. Similarly, APPC/PC also provides a TP_ID for 
a transaction program started by an incoming 


ALLOCATE. 


RETURN_CODE indicates whether APPC/PC accepts 
the TP_STARTED request. See Appendix C, “Verb 
Return Codes,” for more information on return codes. The 
TP STARTED return codes are as follows: 


e BAD_LU_ID: APPC/PC does not recognize the 
LU_ID. 
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TOO_MANY_TPS: APPC/PC is already running the 
maximum number of transaction programs that can be 
run concurrently on this LU (as defined with the 
MAX_TPS parameter in the ATTACH _LU verb). 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


e APPC_ABENDED 
e APPC_ BUSY 

e APPC_ DISABLED 
e OK. 

Note: 


If an incoming ALLOCATE is in the process of being 
rejected, it counts against the MAX TPS parameter until 
rejection is complete. Therefore, for the 
TOO_MANY_TPS return code, you may wish to retry the 
TP STARTED verb. 
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TP_VALID 


Notifies APPC/PC of the status of an incoming 
ALLOCATE that the application subsystem has dequeued 
with the GET_ALLOCATE verb. A valid status indicates 
that the application subsystem has validated and loaded 
the new transaction program. The application subsystem 
must issue a TP_ VALID verb before issuing any 
conversation verbs for the new transaction program. 


Supplied Parameters: 
TP_VALID TP_ID (variable) 


CREATE _TP PTR (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for this transaction 
program. APPC/PC returns this value in the 
CREATE_ TP structure when the application subsystem 
uses the GET ALLOCATE verb. The transaction 
program must use this identifier when it issues any 
conversation verbs for APPC/PC to perform. 


CREATE_TP_PTR specifies the pointer to the 
CREATE_TP structure that APPC/PC returned in 
response to the previous GET_ALLOCATE verb. The 
application subsystem should specify whether the TP 
name is valid or invalid in the SENSE CODE field of the 
CREATE_TP record. 


For a list of the valid sense codes, see “CREATE TP” on 
page 5-66. 
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Returned Parameters: 


RETURN_CODE indicates whether APPC/PC accepts 
the TP_VALID request. See Appendix C, “Verb Return 
Codes,” for more information on return codes. The 
TP_VALID return codes are as follows: 


BAD_TP_ID: APPC/PC does not recognize the 
TP_ID specified with the TP_VALID verb. 


BAD CONV_ID: APPC/PC does not recognize the 
CONV_ID in the CREATE_TP record. 


BAD STATE: TP VALID does not follow a 
GET ALLOCATE. 


For detailed information on the following return codes, 
see “Understanding Control Verb Return Codes” on 
page 5-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 

INCOMPLETE (possible only if the incoming 
ALLOCATE is rejected with a non-0 sense code) 
OK. 


Note: 


APPC/PC, not the transaction program, manages the 
storage for the CREATE_TP structure; the transaction 
program should not allocate or free storage for this 
record. 
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APPC/PC to Application 
Subsystem 


APPC/PC uses the following verbs to request actions from 
an application subsystem. 


In the descriptions of these verbs, APPC/PC provides the 


supplied parameters and the application subsystem 
provides the returned parameters. 
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ACCESS_LU_LU_PW 


Requests the application subsystem to provide APPC/PC 
with an LU-LU password for a specified partner LU. The 
application subsystem configures the local LU security 
capabilities for each partner LU by using the 
ATTACH LU verb. The ATTACH LU verb tells whether 
the session with a partner LU requires the validation of 
session-level security. APPC/PC requests an LU-LU 
password for the validation of session-level security only 
when both partner LUs are configured to use session-level 
security. 


The application subsystem should maintain system-defined 
LU-LU passwords for each partner LU in a manner as 
secure as possible. The application subsystem specifies 
the user exit routine for the ACCESS. _LU_LU_PW call 
in the ATTACH _LU verb. 


Warning: You may not use DOS (or BIOS) functions in 
this exit unless APPC/PC is disabled when such functions 
are issued. For more information, see 

Chapter 2, “Developing an Application Subsystem.” 


Supplied Parameters: 
ACCESS_LU_LU_PW LU_ID (variable) 


LU_NAME (variable) 
PARTNER_LU_NAME (variable) 


PARTNER_FULLY_QUALIFIED_LU_NAME 
(variable) 


Returned Parameters: 


PASSWORD_AVAILABLE (YES) 
(NO) 


PASSWORD (variable) 
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Supplied Parameters: 


LU_ID indicates the identifier of the local LU for which 
APPC/PC is processing the session security. APPC/PC 
returns this value when the application subsystem 
identifies and initializes the LU by using the 
ATTACH LU verb. (See “ATTACH LU” on page 5-7 for 
more details.) 


LU_NAME indicates the local LU name for which 
APPC/PC is processing the session security. 


PARTNER_LU_NAME indicates the partner LU name 
for which the application subsystem should return an 
LU-LU password. 


PARTNER FULLY_QUALIFIED LU_NAME 
indicates the fully qualified name of the LU for which the 
transaction program should return an LU-LU password. 
The fully qualified name consists of the name of the 
network (if any), a period (EBCDIC X’4B’), and the 
LU_NAME. If the network name is blank the period is 
omitted and the fully qualified name is the same as the 
LU name. 


Returned Parameters: 


PASSWORD_AVAILABLE specifies whether an LU-LU 


password is available for this LU-LU session. 


PASSWORD specifies the LU-LU password that the 
application subsystem returns for the specified partner 
LU. The LU-LU password must be a byte string 
consisting of 8 bytes of binary values 0 through 255. If 
the password is shorter than 8 bytes, the application 
subsystem must pad this field to the right with Os. 


Notes: 
1. APPC/PC, not the application subsystem, manages 
storage for ACCESS LU_LU_PW;; the application 


subsystem should not allocate or free storage for this 
record. 
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2. APPC/PC supplies all names exactly as you specified 
them (in EBCDIC). You can use the CONVERT verb 
to convert EBCDIC names to ASCII. 
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CREATE_TP 


Notifies the application subsystem that APPC/PC has 
received an incoming ALLOCATE, and requests that the 
application subsystem initiate a new transaction program 
and attach it to the conversation being requested by the 
incoming ALLOCATE. APPC/PC assigns a TP_ID for the 
newly initiated transaction program and a CONV_ID 
identifier for the conversation. 


If the application subsystem does not accept the 
parameters of the conversation (such as the transaction 
program name or synchronization level), it returns a non-0 
value in the SENSE_CODE parameter of the verb. This 
non-0 value indicates that APPC/PC should reject the 
incoming ALLOCATE with that sense code (sent to the 
partner LU). 


Warning: You may not use DOS (or BIOS) functions in 
this exit unless APPC/PC is disabled when such functions 
are issued by the transaction program. For more 
information, see Chapter 2, “Developing an Application 
Subsystem.” | 
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Supplied Parameters: 
CREATE_TP LU_ID (variable) 


TP_ID (variable) 


PARTNER_FULLY_QUALIFIED_LU_NAME 
(variable) 


PARTNER_LU_NAME (variable) 
MODE_NAME (variable) 
CONV_ID (variable) 

TPN (variable) 


TYPE (BASIC_CONVERSATION) 
(MAPPED_CONVERSATION) 


SYNC_LEVEL (NONE) 
(CONFIRM) 


PASSWORD (variable) 
USER_ID (variable) 


ALREADY_VERIFIED (YES) 
(NO) 


Returned Parameters: 
SENSE_CODE (variable) 
ERROR_DATA_LENGTH (variable) 


ERROR_DATA (variable) 


Supplied Parameters: 


LU_ID indicates the identifier for the local LU under 
which the application subsystem should initiate the 
transaction program. APPC/PC returns this value when 
the application subsystem identifies and initializes the LU 
with the ATTACH LU verb. (See “ATTACH _LU” on 
page 5-7 for more details.) 


TP _ID indicates the identifier for the new instance of the 
transaction program. 
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PARTNER_FULLY_QUALIFIED_LU_NAME 
indicates (if known) the fully qualified name of the LU 
where the remote transaction program is located. The 
fully qualified name consists of the network identifier, a 
period (EBCDIC X’4B’), and the LU_NAME. If the 
network name is blank the period is omitted and the fully 
qualified name is the same as the LU name. 


PARTNER_LU_NAME indicates the name of the remote 
LU from which the request came. For allocating a 
session, the local LU knows the remote LU by this name; 
that is, the PARTNER LU_NAME is the LU network 
name. 


MODE_NAME indicates the mode name for the session 
on which the application subsystem received the 
ALLOCATE. 


CONV _ID indicates the identifier of the new 
conversation. 


TPN indicates the name of the transaction program that 
the application subsystem is to initiate and connect at 
this end of the conversation. 


TYPE indicates the type of conversation that the 
application subsystem is to allocate. 


e BASIC CONVERSATION indicates the allocation of 
a basic conversation. 


e MAPPED CONVERSATION indicates the allocation 
of a mapped conversation. 


SYNC_LEVEL indicates the synchronization level that 
the remote program indicated for this conversation. 


e NONE indicates that the programs do not perform 
confirmation processing on this conversation. The 
programs do not issue verbs and do not recognize any 
returned parameters relating to the synchronization 
function. 
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e CONFIRM indicates that the programs can perform 
confirmation processing on this conversation. The 
programs can issue verbs and recognize returned 
parameters relating to confirmation. 


PASSWORD indicates the conversation-level security 
password that the remote transaction program provided to 
access the specified local transaction program. 


USER_ID indicates the conversation-level user ID that 
the remote program provided to identify itself. 


ALREADY_VERIFIED indicates whether the partner 
LU has already validated the conversation-level password 
and user ID. 


Returned Parameters: 


SENSE_CODE specifies the value that indicates to 
APPC/PC whether the initiation request is acceptable (0) 
or not acceptable (non-0). If the application subsystem 
does not accept the request, it does not initiate a new 
instance of the specified transaction program. APPC/PC 
does not perform any validity checking of the 
SENSE_CODE to guarantee that it is a legal sense code, 
it only returns the sense code to the partner LU. The 
currently defined APPC sense codes are: 


e OK (X’00000000’) 


e TP NAME NOT_RECOGNIZED(X’10086021’): The 
application subsystem does not recognize the 
transaction program name. Although the application 
subsystem may actually recognize the transaction 
program name, it may not be able to initiate the 
transaction program using the designated partner LU 
or mode name. 


e TP _NOT_AVAIL_RETRY(X’084B6031’): The TPN 
exists but is temporarily unavailable. The remote 
program can try again later. 


e TP_NOT_AVAIL_NO_RETRY(X’084C0000’): The 
TPN exists but is permanently unavailable. The 
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remote program cannot try again later without further 
operator action. 


e SYNC_LEVEL_ NOT _SUPPORTED(X’10086041’): The 
remote program specified an unrecognized or 
unacceptable SYNC_LEVEL type for this transaction 
program. 


e CONVERSATION TYPE MISMATCH(X’10086034’): 
The remote program specified an unrecognized or 
unacceptable conversation type for this transaction 
program. 


e SECURITY _NOT_VALID(X’080F6051’): The 
application subsystem rejects the password or user ID, 
or the local transaction program requires security but 
the remote program did not supply a user ID. 


ERROR _DATA_LENGTH specifies the length of the 
error data APPC/PC adds to the error notification it sends 
to the partner LU. 


ERROR_DATA specifies the data that APPC/PC adds to 
the error notification it sends to the partner LU, if the 
parameters and characteristics for this initiation request 
are unacceptable to the application subsystem. Note that 
this data must be an appropriately formatted error log 
data GDS variable, with the correct GDS ID. (For more 
information, see “GDS Variables” in the SNA Reference 
Summary.) APPC/PC does not check the validity of this 
data, but if the application subsystem improperly forms 
this variable, the partner LU may deactivate the session. 


State Changes (when SENSE_CODE indicates OK): 
APPC/PC places the conversation in receive state for the 
local transaction program to receive information from the 
remote partner program. 

Notes: 

1. APPC/PC does not permit the transaction program to 


start issuing verbs from within the CREATE_TP exit 
routine. The exit code of the application subsystem 
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must verify the parameters of the initiation request 
and save all appropriate information. The application 
subsystem can then use this information to initiate the 
transaction program later. 


. After the application subsystem initiates the 


transaction program, the conversation enters receive 
state. 


. APPC/PC, not the application subsystem, manages the 


storage for the CREATE_TP structure; the application 
subsystem should not allocate or free the storage for 
this structure. 


You must specify the 

PARTNER _FULLY_QUALIFIED LU_NAME, 
PARTNER_LU_NAME, MODE_NAME, TPN, 
PASSWORD, and USER_ID in EBCDIC. You can use 
the CONVERT verb to convert these parameters from 
ASCII to EBCDIC. 
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SYSLOG 


Notifies the application subsystem that APPC/PC detected 
an error or that another program detected an error and 
informed APPC/PC. These types of errors include a 
DLC-detected transmission error, abnormal session 
terminations resulting from protocol errors detected at 
either the local or remote LU, and a locally or remotely 
detected conversation-level error. The application 
subsystem processes and handles these errors by reporting 
the errors to the human operator, saving the information 
for later analysis, or discarding the information. 


Errors detected in an LU use the system log exit specified 
in the ATTACH _LWU issued for that LU. Errors detected 
in the PU and network management messages (NMVTs) 
use the system log exit specified in ATTACH _PU. 


Warning: You may not use DOS (or BIOS) functions in 
this exit unless APPC/PC is disabled when such functions 
are issued by the transaction program before issuing the 
macro. For more information, see Chapter 2, “Developing 
an Application Subsystem.” 


Supplied Parameters: 
SYSLOG } PU_OR_LU_NAME (variable) 

TP_ID (variable) 

CONV_ID (variable) 

TYPE (variable) 

SUBTYPE (variable) 

DATA_LENGTH (variable) 


DATA (variable) 


ADDITIONAL_INFO (variable) 
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Supplied Parameters: 


PU_OR_LU_NAME (in EBCDIC) incidates the name of 
the local LU or PU that detected the error. 


TP_ID indicates the identifier for the transaction 
program, if any, that detected the error. APPC/PC passes 
the TP_ID to the application subsystem when the 
application subsystem initiates the program using the 

TP STARTED verb (see “TP_STARTED” on page 5-58) 
or using the CREATE_TP verb (see “CREATE _TP” on 
page 5-66). 


CONV _ID indicates the identifier of the conversation, if 
any, on which APPC/PC detected the error. 


TYPE identifies the major category of error detected. For 
a list of type codes, see Appendix D, “SYSLOG Type 
Codes.” 


SUBTYPE identifies the specific error type within the 
major TYPE category. For locally or remotely detected 
session errors or conversation-level errors, the SUBTYPE 


contains the specific sense code. For a list of the subtype 
codes, see Appendix D, “SYSLOG Type Codes.” 


DATA _ LENGTH indicates the length of the data 
conveyed with the error notification. 


DATA is any character data conveyed along with the 
error notification. APPC/PC passes data associated with 
a conversation-level error to the application subsystem 
using this parameter. 


ADDITIONAL _INFO identifies a pointer to additional 
information about the error. For more detail, see 
“Understanding Link Error Data” on page D-9. 


Notes: 
1. Not all parameters are available for all types of error 
notifications. If a TP_ID, CONV_ID, or SUBTYPE is 


unavailable in a particular log message, the parameter 
value is 0. For example, if APPC/PC detects a DLC 
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hardware error, the PU_OR_LU_NAME contains the 
PU name, but the TP_ID and CONV_ID parameters 
contain a value of 0 to indicate that the application 
subsystem should ignore them. 


2. The DATA and ADDITIONAL INFO parameters are 
meaningful for certain types of SYSLOG. 
Appendix D, “SYSLOG Type Codes,” identifies these 
types. 


3. APPC/PC directs abnormal termination logs only to 
the PU system log exit. 


4. APPC/PC, not the application subsystem, manages 
storage for SYSLOG; the application subsystem should 
not allocate or free the storage for this structure. 


5. You must specify the PU_OR LU NAME in 


EBCDIC. You can use the CONVERT verb to convert 
this parameter value from ASCII to EBCDIC. 
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Activating and Deactivating a 
Node 


The following procedures and examples describe how to 
activate and deactivate an APPC/PC node. 


Activating a Node 


Follow these steps to prepare for transaction program 
conversations and then activate a transaction program. 


1. Define the local PU using ATTACH_PU. 


2. Define local LUs and their potential partner LUs using 
ATTACH_LU. 


3. Activate the DLCs using ACTIVATE_DLC. 


4. If you are using an SDLC switched connection, dial 
the number to establish the connection. If you are 
issuing a CNOS verb for a single session, you do not 
need to dial until you are ready to start the 
conversation. You must dial before issuing CNOS if 
you are using parallel sessions or you have specified 
the AUTO_ACTIVATE option on the CNOS verb. 


5. Use CNOS to set the mode session limit (for a specified 
partner LU and mode) so that there are enough 
sessions to satisfy session activation requests (that is, 
both incoming and local session activation requests). 


For parallel sessions, use CNOS to set the mode 
session limit for the SNASVCMG mode so that the 
corresponding LUs can perform CNOS negotiation. 
Next, set the mode session limit for the mode you want 
to use for a conversation. The application subsystem 
must raise both single- and parallel-session limits from 


6. Initiate a transaction program resulting from an 
incoming ALLOCATE or start a local transaction 
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program by issuing the TP_STARTED verb from the 
application subsystem. Use the passthrough verbs to 
set up the transaction program (For more information 
see “Communicating Identifiers,” on page 2-6). 


7. Issue conversation verbs from within the transaction 
program. 


Example: Activating a Simple Configuration 


The following examples show the configuration of a single 
LU (APPCLU1) with a single partner LU (APPCLU2) at 
ring address ADDR2. An IBM Token-Ring Network 
connects these LUs, which use only a single session with 
a mode name of APPCMODE. 


ATTACH_PU 
PU_NAME (APPCPU) 
ATTACH _LU 

LU_NAME (APPCLU1) 

LU_SESSION_LIMIT (1) 
PARTNER_LU_NAME (APPCLU2) 
PARTNER_LU_SESSION_LIMIT (1) 
PARTNER_LU_DLC_NAME (ITRN) 
PARTNER_LU_ADAPTER_NUMBER (0) 
PARTNER_LU_ADAPTER_ADDRESS (ADDR2) 

MODE_NAME (APPCMODE) 
MODE_MAX NEGOTIABLE_SESSION_LIMIT (1) 

LU_ID (LU_ID) /*** RETURNED ***/ 

ACTIVATE_DLC 

DLC_NAME (ITRN) 


At this point the partner LUs are defined and the adapter 
is open. Communication to partner LU APPCLU2 can 
begin. 


CNOS 
LU_ID (LU_ID) /*** FROM ATTACH LU ***/ 
PARTNER_LU_NAME (APPCLU2) 
MODE_NAME_ SELECT (ONE, APPCMODE) 
PARTNER_LU_MODE_SESSION_LIMIT (1) 


If the transaction is to be locally initiated, enter the name 
of the transaction program at the DOS prompt or at the 
prompt displayed by the application subsystem. The 
transaction program then uses the passthrough verbs to 


5-76 


direct the application subsystem to issue the 
TP_STARTED verb. 


Note: 


You may want to issue a single-session CNOS verb before 
the ACTIVATE DLC verb to ensure that both sides have 
raised their session limits before you attempt to start 
conversations. 


Deactivating a Node 


Follow these steps to terminate a transaction program, 
release the APPC/PC conversations allocated to this 
program, detach the PU, and unload APPC/PC. 


1. After all conversations have ended, issue TP_ENDED 
to indicate the termination of the transaction program. 


2. Reset the mode session limits to 0 using the CNOS 
verb. Resetting these limits causes APPC/PC to 
deactivate the sessions used by the transaction 
program for conversations. 


3. Undefine the local PU using the 
DETACH_PU(TYPE=SOFT) verb. 


4, Enter APPCUNLD at the DOS prompt to unload 
APPC/PC. 


Example: Deactivating a Simple Configuration 


TP_ENDED 

TP_ID (TP_ID) /*** FROM TP_STARTED ***/ 
CNOS 

LU_ID (LU_ID) /*** FROM ATTACH LU ***/ 


PARTNER_LU_NAME (APPCLU2) 

MODE_NAME_ SELECT (ONE, APPCMODE) 

PARTNER_LU_MODE_SESSION_LIMIT (0) 
DETACH_PU 

TYPE (SOFT) 
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Chapter 6. Using Transaction 
Mapped Conversation Verbs 


This chapter describes the category of verbs called 
mapped conversation verbs. Mapped conversation verbs 
define the Mapped Conversation API for end-user 
program-to-program support. In particular, the mapped 
conversation protocol is for use by transaction programs. 


Before the detailed descriptions of the mapped 
conversation verbs is a discussion of the conversation 
states and common error codes at the mapped 
conversation protocol boundary and a description of the 
mapped conversation return codes and abnormal 
termination conditions. These subjects apply generally to 
all the mapped conversation verbs. 


Understanding Mapped 
Conversation States 


The selection of verbs that a program can issue for a 
particular mapped conversation depends on the state of 
the mapped conversation. As the program issues verbs, 
the state of the mapped conversation can change. This 
state change is a result of the function of the verb, a verb 
issued by the remote program, or of network errors. 


APPC/PC defines the state of a mapped conversation in 
terms of the local program’s view of the local end of the 
mapped conversation. The states of other mapped 
conversations allocated to the program can be different. 
For example, one mapped conversation can be in receive 
state and another in send state, concurrently. 
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The state of the mapped conversation determines the verbs 
that APPC/PC allows a program to issue. The table below 
correlates the verbs, and parameters if applicable, to the 
mapped conversation states. 


Conversation States at 
Mapped Conversation 
Protocol Boundary 


Verb 


MC_CONFIRMED 


MC_DEALLOCATE with 
TYPE(FLUSH) or 
TYPE(SYNC_LEVEL) 


MC_DEALLOCATE with 


TYPE(ABEND) 


MC_FLUSH 


MC_GET_ATTRIBUTES 


GET_TYPE la 


MC_PREPARE_TO_RECEIVE 
MC_RECEIVE_AND_ WAIT 


MC_SEND_DATA 


MC_SEND_ERROR 


MC_TEST 


At the intersection of each verb row and state column, the 
table indicates Yes, No, or n/a. Yes means that APPC/PC 
allows the program to issue the verb when the mapped 
conversation is in that state. 


No means the program cannot issue the verb because 
APPC/PC disallows the verb in that state. APPC/PC 
treats a verb issued for a mapped conversation in a 
disallowed state as a state-check condition. The 
individual verb descriptions list the applicable state-check 
conditions. 


n/a means the state is not applicable either because it 


cannot exist when the verb is issued or because the state 
is not relevant to the verb. 
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A mapped conversation enters a particular state when the 
program issues a verb that causes a state transition or 
when the program receives a returned value that indicates 
a state transition has occurred. This chapter defines the 
specific state transitions in the individual verb 
descriptions under the heading “State Changes” in the 
return code descriptions and under the following heading, 
“Understanding Mapped Conversation Return Codes.” 


Understanding Mapped 
Conversation Return Codes 


All conversation verbs have a parameter called 
RETURN_CODE that APPC/PC uses to pass a return 
code back to the transaction program after the LU 
finishes executing a verb. The return code indicates the 
results of verb execution, including any state changes to 
the specified mapped conversation. For information on 
which verbs a program can issue in each state, see 
“Understanding Mapped Conversation States” on 

page 6-1. 


The structure of a RETURN_CODE parameter is a 2-byte 
primary code identifying the error type, and a 4-byte 
secondary code which provides more detailed error 
information. 


Some of the return codes indicate results of the local LU’s 
processing of a verb; APPC/PC returns these return codes 
with the verb that initiated the local processing. Other 
return codes indicate results of processing initiated at the 
remote end of the mapped conversation. 


Depending on the verb, APPC/PC returns these return 
codes with the verb that initiated the remote processing or 
with a subsequent verb. Still other return codes report 
events occurring at the remote end of the mapped 
conversation. In any case, APPC/PC returns only one 
return code at a time. 
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Appendix C, “Verb Return Codes” provides detailed 
information on all return codes, including the actions you 
should take. 


The following return codes can be returned on one or 
more mapped conversation verbs: 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
CONVERSATION_TYPE_MIXED 
DEALLOCATE_ABEND 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
INVALID_VERB 

OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING. 


Detailed descriptions of these return codes follow. Brief 
references to these return codes appear in the individual 
verb descriptions later in this chapter. 


ALLOCATION_ERROR indicates that the local 
transaction program issued an MC_ALLOCATE and 
APPC/PC could not complete the allocation of the 
specified mapped conversation. The 

ALLOCATION. ERROR indication and one of the 
following secondary return codes form the complete return 
code that APPC/PC returns to the transaction program; 
the secondary return code identifies the specific error. 


The remote LU and remote transaction program referred 
to in the following secondary return code definitions are 
the LU specified in the PARTNER _ LU _ NAME parameter 
and the transaction program specified in the TPN 
parameter, respectively, of the MC_ALLOCATE verb. 


APPC/PC reports allocation errors caused by the local LU 
failing to obtain a session for the conversation on the 
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MC_ALLOCATE verb, and by the remote LU rejecting 
the allocation request on a subsequent verb. 


Whenever APPC/PC returns an ALLOCATION ERROR 
return code to the program, it places the mapped 
conversation in reset state. 


The ALLOCATION_ERROR secondary return codes are: 


e ALLOCATION FAILURE _NO_RETRY indicates 
that APPC/PC cannot allocate the mapped 
conversation on a session because of a permanent 
condition. For example, APPC/PC cannot activate the 
session to be used for the mapped conversation because 
the current mode session limit for the specified partner 
LU is 0; or because of a system definition error or a 
session-activation protocol error; or because APPC/PC 
deactivated the session in response to a session 
protocol error before it could allocate the mapped 
conversation. The transaction program should not try 
the conversation again until it corrects the condition. 


e ALLOCATION _FAILURE_RETRY indicates that 
APPC/PC cannot allocate the mapped conversation on 
a session because of a temporary condition. For 
example, APPC/PC cannot allocate a session for the 
mapped conversation because of a temporary lack of 
resources at the local LU or remote LU, or because 
APPC/PC deactivated the session due to a line or 
modem failure before it could allocate the mapped 
conversation. 


The condition is temporary; the transaction program 
can try the conversation again. However, to avoid 
congesting the network with attempted allocation 
requests, the transaction program should pause or wait 
for a keystroke before retrying the conversation. 


e CONVERSATION_TYPE_MISMATCH indicates 
that the remote LU rejects the allocation request 
because either it does not support mapped 
conversations, or the remote transaction program does 
not support the mapped conversation protocol 
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boundary. APPC/PC returns this return code on a 
subsequent verb. 


PIP_NOT_ALLOWED indicates that the remote LU 
rejects the allocation request because the local 
program specified program initialization parameters 
(by setting the PIP_DATA LENGTH parameter to a 
non-0 value) and either the remote LU does not 
support PIP data, or the remote transaction program 
has no PIP variables defined. APPC/PC returns this 
return code on a subsequent verb. 


PIP_NOT_SPECIFIED_ CORRECTLY indicates 
that the remote LU rejects the allocation request 
because the remote transaction program has one or 
more PIP variables defined and the local transaction 
program has specified that there are no program 
initialization parameters (by setting the 

PIP_DATA LENGTH parameter to 0). 


This error can also indicate that the local transaction 
program has specified program initialization 
parameters (by setting the PIP_DATA LENGTH 
parameter to a non-0 value) that do not correspond in 
number to those defined for the remote transaction 
program. APPC/PC returns this return code on a 
subsequent verb. 


SECURITY_NOT_VALID indicates that the remote 
LU rejects the allocation request because the access 
security information (specified using the 
MC_ALLOCATE SECURITY parameter) is invalid. 
APPC/PC returns this return code on a subsequent 
verb. 


SYNC_LEVEL_NOT_SUPPORTED indicates that 
the remote LU rejects the allocation request because 
the local transaction program specified a 
synchronization level (using the SYNC_LEVEL 
parameter) that the remote transaction program does 
not support. APPC/PC returns this return code on a 
subsequent verb. 


e TPN NOT RECOGNIZED indicates that the remote 
LU rejects the allocation request because the local 
transaction program specified a remote transaction 
program name that the remote LU does not recognize. 
APPC/PC returns this return code on a subsequent 
verb. 


e TRANS _ PGM_NOT_AVAIL_NO_RETRY indicates 
that the remote LU rejects the allocation request 
because the local transaction program specified a 
remote transaction program that the remote LU 
recognizes but cannot start. The condition is 
permanent; the transaction program should not try the 
conversation again. APPC/PC returns this return code 
on a subsequent verb. 


e TRANS _ PGM NOT_AVAIL_ RETRY indicates that 
the remote LU rejects the allocation request because 
the local transaction program specified a remote 
transaction program that the remote LU recognizes but 
currently cannot start. The condition is temporary; 
the transaction program can try the conversation 
again. APPC/PC returns this return code on a 
subsequent verb. 


APPC_ABENDED indicates that APPC/PC has been 
abnormally terminated. 


APPC_BUSY indicates that APPC/PC is currently 
executing another verb and cannot execute this verb. 
This error can occur if a verb is issued after APPC/PC 
execution is interrupted (for example, by a Ctrl-Break or 
timer interrupt). 


APPC_DISABLED indicates that APPC/PC is disabled 
as a result of the DISABLE/ENABLE_APPC verb. 


CONV_FAILURE_NO_RETRY indicates that a failure 
occurred that caused APPC/PC to terminate the mapped 
conversation prematurely. For example, APPC/PC 
deactivated the session that the transaction programs 
were using for the mapped conversation because of a 
session protocol error, or APPC/PC deallocated the 
mapped conversation because of protocol error between 
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the mapped conversation components of the LUs. The 
condition is permanent; the transaction program should 
not try the conversation again until the condition is 
corrected. APPC/PC can report this return code to the 
local transaction program with a verb it issues in any 
state other than reset. APPC/PC places the mapped 
conversation in reset state. 


CONV_FAILURE_RETRY indicates that a failure 
occurred that caused APPC/PC to terminate the mapped 
conversation prematurely. For example, APPC/PC 
terminates conversations when it must deactivate the 
associated sessions in response to a line or modem failure. 
The condition is temporary; the transaction program can 
try the conversation again. However, to avoid congesting 
a network with attempted allocation requests, the 
transaction program should pause or wait for a keystroke 
before retrying the transaction. APPC/PC can report this 
return code to the local transaction program on a verb 
that the transaction program issues in any state other 
than reset. APPC/PC places the mapped conversation in 
reset state. 


CONVERSATION_TYPE_ MIXED indicates that the 
local transaction program issued both basic and mapped 
conversation verbs for the same conversation. APPC/PC 
reports this return code with the verb issued. The state of 
the mapped conversation remains unchanged. 


DEALLOCATE ABEND indicates that the remote 
transaction program issued an MC_ DEALLOCATE verb 
specifying the TYPE(ABEND) parameter. The remote LU 
can also issue an MC_DEALLOCATE verb specifying the 
TYPE(ABEND) parameter in response to a remote 
transaction program abnormal termination condition. If 
the mapped conversation for the remote transaction 
program was in receive state when the remote transaction 
program or LU issued an MC_ DEALLOCATE, 
information sent by the local transaction program and not 
yet received by the remote transaction program is purged. 


APPC/PC returns the DEALLOCATE ABEND return 


code to the local program with a verb the program issues 
in either send or receive state. After APPC/PC issues this 
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return code, it places the mapped conversation in reset 
state. 


DEALLOCATE_NORMAL indicates that the remote 
transaction program issued an MC_DEALLOCATE verb 
specifying the TYPE(SYNC_LEVEL) where the 
synchronization level of the conversation is NONE or 
TYPE(FLUSH) parameter. APPC/PC reports this return 
code to the local transaction program on a verb the 
program issues in receive state. APPC/PC leaves the 
mapped conversation in reset state. 


INCOMPLETE indicates that the verb has not finished 
and must be re-issued unchanged before any other verb 
with the same TP_ID. Before re-issuing the verb, you 
should try to issue verbs on other transaction programs, 
including other unfinished verbs. If you are queueing 
incoming ALLOCATEs in the LUs, you should also 
periodically issue GET ALLOCATE. This return code is 
returned only if ATTACH PU 
(RETURN_CONTROL=INCOMPLETE) was issued. For 
more information on this return code, see “System 
Deadlocks” on page 10-2. 


INCOMPLETE_ALTERED_VERB indicates that a verb 
was issued with the same TP_ID as that of an unfinished 
verb, or the unfinished verb was altered before it was 
re-issued. 


Note: You may change the first 12 bytes of an incomplete 
verb so that you can place list pointers in this area to 
create a list of incomplete verbs. 


INVALID_VERB indicates that APPC/PC did not 
recognize the verb operation code of the issued verb. 
APPC/PC reports this return code on the verb issued. The 
state of the mapped conversation remains unchanged. 


OK indicates that APPC/PC executed the verb 
successfully. That is, APPC/PC performed the function 
defined for the verb, up to the point at which it returns 
control to the transaction program. The state of the 
mapped conversation is as defined for the verb. 
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PROG_ERROR_NO_TRUNC indicates that the remote 
program issued an MC_SEND_ERROR verb and the 
mapped conversation for the remote transaction program 
was in send state. No truncation of data occurs at the 
mapped conversation API. 


APPC/PC reports this return code to the local transaction 
program on an MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_ IMMEDIATE verb that the transaction 
program issues before receiving data records or after 
receiving one or more complete data records. The mapped 
conversation remains in receive state. 


PROG_ERROR PURGING indicates that the remote 
transaction program issued an MC_SEND_ERROR verb, 
and the mapped conversation for the remote transaction 
program was in receive or confirm state. The 
MC_SEND_ERROR may cause data sent by the local 
transaction program to be purged. 


Purging occurs when a transaction program issues 
MC_SEND_ERROR in receive state before receiving all 
the information sent by its partner transaction program. 
That is, APPC/PC purges the information sent before it 
reports the error. 


The purging can occur at the local LU, the remote LU, or 
both. No purging occurs when a transaction program 
issues MC_SEND_ ERROR in confirm state or receive 
state after receiving all the information sent by its 
partner program. 


APPC/PC normally reports this return code to the local 
transaction program with a verb that the local transaction 
program issues after sending some information to the 
remote transaction program. However, APPC/PC can 
report the return code with a verb that the program issues 
before sending any information, depending on the verb 
and when the program issues it. APPC/PC leaves the 
mapped conversation in receive state. 
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Note: 


The PARAMETER_CHECK and STATE_CHECK errors 
can also occur on any verb. When APPC/PC detects these 


error conditions, it does not try to execute the verb. A 
PARAMETER CHECK error occurs when APPC/PC 


detects an invalid parameter value. A STATE CHECK 
error occurs when the conversation is not in the correct 
state for the verb the transaction program is issuing. The 


verb descriptions list the secondary return codes that 


identify the causes of these errors. 


The table below correlates the return codes to the verbs 


on which they can be returned. 


Return Codes 


ALLOCATION_ERROR 
APPC_ ABENDED 

APPC BUSY 

APPC DISABLED 

CONV FAILURE NO RETRY 
CONV FAILURE RETRY 
CONVERSATION TYPE MIXED 
DEALLOCATE ABEND 
DEALLOCATE NORMAL 
INCOMPLETE 

INCOMPLETE ALTERED VERB 
OK 

PARAMETER CHECK 

PROG ERROR NO TRUNC 
PROG ERROR PURGING 
STATE CHECK 
UNSUCCESSFUL 
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Each X in the table means that APPC/PC can return the 
return code with the corresponding verb. 


The individual verb descriptions list the applicable return 
codes. The descriptions for most verbs do not explicitly 
list the secondary return codes of ALLOCATION ERROR 
because they can occur at any time and are not 
necessarily a result of the verb on which they are 
returned. The description of the MC_ALLOCATE verb, 
however, lists the two secondary return codes that 
indicate an allocation failure. 
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Verb Descriptions 


Detailed descriptions of the mapped conversation verbs 
follow. 


MC_ALLOCATE 


Allocates a session, if one is available, between the local 
LU and a remote LU, and establishes a mapped 
conversation between the local transaction program and a 
remote transaction program on that session. APPC/PC 
assigns a CONV_ID to the conversation. Except for the 
first conversation of a remotely initiated transaction 
program, the transaction program must issue this verb 
before it can issue any verbs that refer to the mapped 
conversation. 
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Supplied Parameters: 
MC_ALLOCATE TP_ID (variable) 
PARTNER_LU_NAME (variable) 
MODE_NAME (variable) 
TPN (variable) 
RETURN_CONTROL 
(WHEN_SESSION_ALLOCATED) 
(IMMEDIATE) 
(WHEN _SESSION_FREE) 


SYNC_LEVEL (CONFIRM) 
(NONE ) 


SECURITY (NONE) 
(SAME ) 
(PGM (USER_ID (variable) 
PASSWORD (variable) ) 
PIP DATA LENGTH (variable) 


PIP DATA (variable) 


Returned Parameters: 


CONV_ID (variable) 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


PARTNER _LU_NAME specifies the name (in EBCDIC) 
of the remote LU at which the remote transaction 
program is located. The local LU uses the 

PARTNER _LU_NAME to identify the remote LU when 
allocating a session. That is, the PARTNER LU NAME 
is the remote LU network name. 


6-14 MC ALLOCATE 


MODE_NAME specifies the mode name (in EBCDIC) 
designating the network properties for the session 
APPC/PC is to allocate for the mapped conversation. For 
example, one network property is the class of service 
APPC/PC provides for the session used. Mapped 
conversations cannot use the SNASVCMG mode. 


TPN specifies the name (in EBCDIC) of the remote 
transaction program that manages the other end of the 
mapped conversation. TPN cannot specify an SNA 
service transaction program name at the mapped 
conversation API. (SNA service transaction program 
names begin with a character value in the range X’00’ to 
X’3F’.) 


RETURN_CONTROL specifies when the local LU is to 
return control to the local transaction program, after the 
program requests the LU to allocate a session for the 
conversation. APPC/PC also reports allocation errors 
caused by the local LU’s failure to obtain a session for the 
conversation on this verb. APPC/PC reports allocation 
errors caused by the remote LU rejecting the allocation 
request on a subsequent verb. The valid values for the 
RETURN_CONTROL parameter are: 


e WHEN_SESSION_ALLOCATED directs the LU to 
allocate a session for the conversation before 
returning control to the transaction program. Except 
for instances of conversation failure, the LU does not 
return control to the program until a session becomes 
available. 


This option may cause a deadlock situation if there are 
not enough sessions for the currently active 
conversations of all transaction programs. Specifying 
the RETURN_CONTROL(IINCOMPLETE) option on 
the ATTACH_PU verb can confine the problem to the 
currently executing transaction program, but if this 
program has itself used up all sessions, the program 
can still cause a deadlock situation by using the 
RETURN_CONTROL(WHEN_SESSION_ALLOCATED) 
option. You must analyze your operating environment 
to determine if this option is safe. For more 
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information on this problem, see “System Deadlocks” 
on page 10-2. 


e IMMEDIATE directs the LU to allocate a session for 
the conversation if a contention-winner session is 
immediately available. This option returns control to 
the transaction program immediately with a return 
code indicating whether a session is allocated. In this 
case, the local LU does not have to wait for a response 
from the partner LU, and the MC_ ALLOCATE verb 
does not require information to be sent to the partner 


LU. 


— A return code of OK indicates that a session is 
immediately available and is allocated for the 
conversation. A session is immediately available 
when it is active, it is not allocated to another 
conversation, and the local LU is the contention 
winner for the session. 


— A return code of UNSUCCESSFUL indicates that a 
session is not immediately available and that the 
LU did not perform the allocation. 


e WHEN_SESSION_FREE directs the LU to allocate 
a session for the conversation only if a session (either 
a contention winner or loser) is available or able to be 
activated, and then to return control to the 
transaction program with a return code indicating 
whether a session is allocated. 


— A return code of OK indicates that a session is 
available and is allocated for the conversation. If 
activation of a session is necessary, the LU 
performs the session activation before returning 
control to the transaction program. 


— A return code of ALLOCATION_ERROR indicates 
that a session is unavailable and that the LU 
cannot activate a new session. No session is 
allocated. 
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SYNC_LEVEL specifies the synchronization level that 
the local and remote transaction programs can use for this 
conversation. 


NONE specifies that the transaction programs do not 
perform confirmation processing on this conversation. 
The programs do not issue verbs and do not recognize 
returned parameters relating to the synchronization 
function. 


CONFIRM specifies that the transaction programs can 
perform confirmation processing on this conversation. 
The programs can issue verbs and recognize returned 
parameters relating to confirmation. 


SECURITY specifies access security information that the 
remote LU uses to validate access to the remote 
transaction program and its conversations. The access 
security information includes a user ID and a password 
provided using the following arguments: 


NONE specifies that this conversation does not use 
conversation-level security. 


SAME informs the remote LU that the user ID has 
already been verified as part of the allocation request 
that initiated execution of the local transaction 
program. APPC/PC saved the user ID when the local 
transaction program was remotely initiated. This 
option also causes APPC/PC to send this saved user ID 
to the remote LU with an ‘already verified’ indication. 
If there was no user ID, APPC/PC sends the allocation 
request with no security information and a ‘not 
already verified’ indication. 


PGM directs the remote LU to use the security 
information that the local transaction program 
provides on this parameter. The local transaction 
program uses the following arguments to provide this 
security information: 


— USER_ID specifies the ID (in EBCDIC) of the end 
user. The USER_ID is 8 bytes long. The remote 
LU uses this value and the password to verify the 
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identity of the end user making the allocation 
request. In addition, the remote LU may use the 
user ID for auditing or accounting to associate 
conversation accesses with the end user. 


— PASSWORD specifies the password (in EBCDIC) 
of the end user. The PASSWORD can be up to 8 
bytes long. The remote LU uses this value and the 
user ID to verify the identity of the end user 
making the allocation request. 


PIP_DATA_ LENGTH specifies the length of the 
program initialization parameters for the remote program. 
Set this parameter to 0 if there is no PIP data. 


PIP_DATA specifies the variable containing the PIP 
data that the local program is sending to the remote 
program. The transaction program must format the PIP 
data according to the GDS format (see “FM Headers” in 
SNA Reference Summary). 


Returned Parameters: 
CONV _ID indicates the ID of the new conversation. 


RETURN_CODE indicates the result of verb execution. 
The MC_ALLOCATE return codes are: 


e PARAMETER _CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


—- DATA AREA ACROSS SEGMENT: APPC/PC 
does not permit PIP data to cross a segment 
boundary. 


— BAD_TPN_LEN: The value that TPN specifies is 
too short (less than 1) or too long (greater than 64). 


—- BAD SYNC_LEVEL: APPC/PC does not 
recognize the specified SYNC_LEVEL. 


6-18 MC ALLOCATE 


— BAD _SECURITY_SELEC: APPC/PC does not 
recognize the specified SECURITY. 


— BAD RETURN CONTROL: APPC/PC does not 
recognize the specified RETURN_ CONTROL. 


— TOO_BIG_SEC_TOKENS: APPC/PC does not 
accept a password or user ID that is longer than 8 
bytes. 


— PIP_LEN_ INCORRECT: APPC/PC does not 
accept PIP data that is longer than 32767 bytes. 


— NO_USE_OF_SNASVCMG: APPC/PC does not 
accept SNASVCMG as the value for the 
MODE_NAME parameter. 


— UNKNOWN_PARTNER MODE: APPC/PC does 
not recognize the specified PARTNER _LU_ NAME 
or MODE_NAME. 


e ALLOCATION_ERROR 


— ALLOCATION _FAILURE_NO_RETRY: 
APPC/PC cannot allocate the conversation because 
of a permanent error condition. 


— ALLOCATION FAILURE RETRY: APPC/PC 
cannot allocate the conversation because of a 
temporary error condition. 


e UNSUCCESSFUL: The program specified 
RETURN_CONTROLUMMEDIATE) and APPC/PC 
could not allocate the conversation because no 
contention-winner sessions were available. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
INCOMPLETE 
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e INCOMPLETE ALTERED VERB 
e OK. 


State Changes: 


The conversation enters send state if the 
RETURN_CODE indicates OK. 


Notes: 


1. The local LU does not send PIP data immediately 
unless the local transaction program issues a verb 
(other than MC_SEND_DATA) that explicitly directs 
the LU to flush its send buffer. Otherwise, the LU 
retains the PIP parameter of the MC_ALLOCATE 
verb and accumulates data from subsequent 


MC_SEND_DATA verbs. 


The LU sends this data to the partner LU when it 
accumulates enough data for transmission. The 
amount of information that is sufficient for 
transmission depends on the characteristics of the 
session allocated for the conversation, and can vary 
from session to session. 


2. The local transaction program can ensure that 
APPC/PC connects the remote transaction program as 
soon as possible by issuing the MC_FLUSH verb after 
the MC_ALLOCATE verb. 


3. Contention for a session can occur when two LUs 
connected by a session both try to allocate a 
conversation on the session at the same time. 
APPC/PC resolves contention by making one LU the 
contention winner of the session and the other LU the 
contention loser of the session. 


The contention-winner LU allocates a conversation on 
a session without asking permission from the 
contention-loser LU. Conversely, the contention-loser 
LU requests permission from the contention-winner LU 
to allocate a conversation on the session. Then the 
contention-winner LU either grants or rejects the 
request. 
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4. The remote transaction program starts the 
conversation in receive state. 


5. For an IBM Token-Ring Network, one link must be 
reserved for outgoing calls to enable the 
MC_ALLOCATE verb to complete. For more 
information on reserving links, see “Entering 
Information for an IBM Token-Ring DLC” in the 
APPC/PC Installation and Configuration Guide 


6. You must specify the PARTNER _LU_ NAME, 
MODE_NAME, TPN, USER_ID, and PASSWORD in 
EBCDIC. You can use the CONVERT verb to convert 
these parameters from ASCII to EBCDIC. 
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MC_CONFIRM 


Sends a confirmation request to a remote transaction 
program and waits for a reply. This verb enables the local 
and remote transaction programs to synchronize their 
processing with one another. MC_CONFIRM also causes 
the LU to flush its send buffer. To use this verb, the 
transaction program must allocate the conversation with 
a synchronization level of CONFIRM. 


Supplied Parameters: 
MC_CONFIRM TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is requesting confirmation. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_CONFIRM return codes are: 


e OK: The remote program replied CONFIRMED. 
e PARAMETER CHECK 
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— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


—- BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— CONFIRM_ON_SYNC_NONE: APPC/PC does 
not permit the program to use this verb if it 
allocated the conversation with 
SYNC_LEVEL(NONE). 


STATE_CHECK 


— CONFIRM BAD STATE: The conversation is not 
in send state. 


— CONFIRM NOT _LL_BDY: The conversation is 
in send state, and the program started, but did not 
finish, sending a logical record. 


For detailed information on the following return codes, 


see “Understanding Mapped Conversation Return Codes’ 


? 


on page 6-3 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
PROG_ERROR_PURGING. 


REQUEST_TO_SEND_RECEIVED indicates whether 
the local LU received an MC_REQUEST_TO_ SEND 
verb. The two indications APPC/PC can return are YES 
and NO. 


YES indicates that the local LU received an 
MC_REQUEST_TO_SEND verb from the remote 
transaction program. The remote transaction program 
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issues an MC_ REQUEST_TO_ SEND verb to request 
the local transaction program to enter receive state 
and place the remote transaction program in send 
state. 


e NO indicates that the local LU has not received an 
MC_REQUEST_TO_SEND notification from the 
remote transaction program 


State Changes: 


If the RETURN_CODE parameter indicates OK, the state 
of the conversation remains the same. 


For more information on state changes when the 
RETURN_CODE indicates other than OK, see 
“Understanding Mapped Conversation Return Codes” on 
page 6-3. 


Notes: 


1. The transaction program can use this verb for various 
application-level functions. For example: 


e The transaction program can issue this verb 
immediately after an MC_ALLOCATE to 
determine whether the allocation of the 
conversation is successful before sending data 


e The transaction program can issue this verb to 
request acknowledgment of data it sent to the 
remote program. The remote program can respond 
by issuing MC_CONFIRMED to indicate that it 
received and processed the data without errors. 
Alternatively, the remote program can issue an 
MC _SEND_ERROR to indicate that it found an 
error. 


2. When the REQUEST _TO_SEND_RECEIVED 
parameter indicates YES, the remote transaction 
program is requesting that the local transaction 
program enter receive state and place the remote 
program in send state. A transaction program enters 
receive state by issuing the 


6-24 MC_CONFIRM 


MC_PREPARE_ TO RECEIVE verb or the 
MC_RECEIVE_AND_ WAIT verb. The transaction 
partner program enters send state after it issues the 
MC_RECEIVE_AND_WAIT verb or the 
MC_RECEIVE_IMMEDIATE verb, and receives the 
SEND indication from its partner transaction program 
on the WHAT _ RECEIVED parameter. 
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MC_CONFIRMED 


Sends a confirmation reply to the remote transaction 
program. This verb enables the local and remote 
transaction programs to synchronize their processing. 
The local transaction program can issue this verb when it 
receives a confirmation request. (For more information 
on confirmation requests, see the WHAT RECEIVED 
parameter of the MC_ RECEIVE AND_WAIT verb.) 


Supplied Parameters: 
TP_ID (variable) 


MC_CONFIRMED 


CONV_ID (variable) 
Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is returning confirmation. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_CONFIRMED return codes are: 


e PARAMETER CHECK 


— BAD _TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


6-26 MC_CONFIRMED 


e STATE CHECK 
— CONFIRMED BAD STATE: The conversation is 


not in confirm state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


The conversation enters receive state if the program 
received CONFIRM on the preceding 
MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_IMMEDIATE. 


The conversation enters send state if the program 
received CONFIRM_SEND on the preceding 
MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_IMMEDIATE. 


The conversation enters reset state if the program 
received CONFIRM_DEALLOCATE on the preceding 
MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_IMMEDIATE. 

Note: 


The program can issue this verb only as a reply to a 
confirmation request. 
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MC_DEALLOCATE 


Deallocates the specified conversation. 
MC_DEALLOCATE can perform the function of the 
MC_CONFIRM verb before it deallocates the 
conversation. APPC/PC discards the conversation ID 
after deallocating the conversation. 


Supplied Parameters: 
MC_DEALLOCATE TP_ID (variable) 


CONV_ID (variable) 


TYPE (SYNC_LEVEL) 
(FLUSH) 
(ABEND) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation that the 
local transaction program is deallocating. 


TYPE specifies the type of deallocation APPC/PC is to 
perform. 


e SYNC_LEVEL directs APPC/PC to deallocate the 
conversation based on the synchronization level 
allocated to this conversation. 


— Ifthe SYNC_LEVEL is NONE, APPC/PC performs 
the function of the MC_FLUSH verb and then 
deallocates the conversation normally. 
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~ Ifthe SYNC_LEVEL is CONFIRM, APPC/PC 
performs the function of the MC_CONFIRM verb 
and, if it is successful (as indicated by a return 
code of OK on this MC_ ALLOCATE verb), 
APPC/PC deallocates the conversation normally. If 
it is unsuccessful, the return code determines the 
state of the conversation. 


FLUSH directs APPC/PC to perform the function of 
the FLUSH verb and then to deallocate the 
conversation normally. When you specify FLUSH as 
the type, the remote partner receives a 
DEALLOCATE_NORMAL following the successful 
deallocation of a conversation. 


ABEND directs APPC/PC to perform the function of 
the FLUSH verb when the conversation is in send 
state, and then to deallocate the conversation 
abnormally by purging data, if necessary. APPC/PC 
purges data when a program deallocates a 
conversation in receive state. 


The remote program is informed of the deallocation by 
a DEALLOCATE_ABEND indication unless the 
remote program has issued an MC_SEND_ERROR. If 
the remote program has issued an 
MC_SEND_ERROR, it may receive a 

DEALLOCATE NORMAL return code instead of 
DEALLOCATE_ABEND. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_DEALLOCATE return codes are: 


PARAMETER _ CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 
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- DEALLOCATE_ BAD TYPE: APPC/PC does not 
recognize the specified TYPE. 


e STATE_CHECK 


— DEALLOC_FLUSH_BAD_STATE: The program 
specified the TYPE(SYNC_LEVEL) parameter for 
a conversation specified with 
SYNC_LEVEL(NONE) and the conversation is not 
in send state. Alternatively, the program may have 
specified TYPE(FLUSH) when the conversation 
was not in send state. 


— DEALLOC_CONFIRM_BAD_ STATE: The 
program specified the TYPE(SYNC_LEVEL) 
parameter for a conversation specified with SYNC _ 
LEVEL(CONFIRM) when the conversation was not 
in send state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_ MIXED 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK. 


APPC/PC can report the following return codes if the 
program specifies TYPE(SYNC_LEVEL) and the 
synchronization level allocated to this conversation is 
CONFIRM. For detailed information on these return 
codes, see “Understanding Mapped Conversation Return 
Codes” on page 6-3 and Appendix C, “Verb Return 
Codes.” 


ALLOCATION_ERROR 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND 
PROG_ERROR_PURGING. 
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State Changes: 


The conversation enters reset state when 
RETURN_CODE indicates OK. 


For information on state changes when RETURN_CODE 
indicates other than OK, see “Understanding Mapped 
Conversation Return Codes” on page 6-3. 


Notes: 


1. A transaction program can use the 
TYPE(SYNC_LEVEL) parameter to deallocate the 
conversation according to the synchronization level 
allocated to the conversation. 


e Ifthe synchronization level is NONE, APPC/PC 
deallocates the conversation unconditionally. 


e Ifthe synchronization level is CONFIRM, 
APPC/PC deallocates the conversation after the 
remote program responds to the confirmation 
request by issuing MC_CONFIRMED. APPC/PC 
does not deallocate the conversation if the remote 


program responds to the confirmation request by 
issuing MC_SEND_ERROR. 


2. A transaction program can use the TYPE(FLUSH) 
parameter to deallocate the conversation 
unconditionally (that is, regardless of its 
synchronization level). 


3. A transaction program can use the TYPE(ABEND) 
parameter to deallocate the conversation 
unconditionally regardless of its synchronization level 
and its current state. Specifically, a transaction 
program uses this parameter when it detects an error 
that prevents useful communication (that is, 
communication leading to successful completion of the 
transaction). The transaction programs define the 
specific use and meaning of ABEND. 
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MC_FLUSH 


Flushes the send buffer of the local LU by sending all 
buffered information to the remote LU. APPC/PC sends 
all of the information stored in the local LU to the remote 
LU. Information buffered by the LU can come from 
MC_ALLOCATE, MC_SEND_ DATA, 

MC_PREPARE TO_RECEIVE, and 
MC_SEND_ERROR. Refer to the descriptions of these 
verbs for more details on this buffered information, 
including when APPC/PC places information in the 
buffer. 


Supplied Parameters: 
MC_FLUSH TP_ID (variable) 


CONV_ID (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 
APPC/PC is to flush the local LU’s send buffer. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_FLUSH return codes are: 


e PARAMETER _CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 
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—- BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


STATE CHECK 
— FLUSH NOT _SEND_ STATE: The conversation 


is not in send state. The MC_FLUSH verb can 
only be issued in send state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


None 


Notes: 


I, 


This verb is useful for reducing the time a remote 
transaction program must wait for data. The LU 
normally buffers the data from consecutive 
MC_SEND_ DATA verbs until it has enough to 
transmit. Then it transmits the buffered data to the 
remote LU. However, the local transaction program 
can issue MC_FLUSH to force the local LU to 
transmit the buffered data, eliminating the wait for the 
buffer to fill. In this way, the local transaction 
program can minimize the time that the remote 
transaction program has to wait to receive the data it 
is to process. 


The LU flushes its send buffer only when it has some 
information to transmit. If the LU has no information 
in its send buffer, it does not transmit anything to the 
remote LU. 
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3. The local transaction program can ensure that 
APPC/PC connects the remote transaction program as 
soon as possible by issuing the MC_FLUSH verb 
immediately after the MC_ ALLOCATE verb. 
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MC_GET_ATTRIBUTES 


Returns information pertaining to the specified mapped 
conversation. 


Supplied Parameters: 
MC_GET_ATTRIBUTES TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 
LU_ID (variable) 
OWN_NET_NAME (variable) 
OWN_LU_NAME (variable) 


PARTNER_LU_NAME (variable) 


PARTNER_FULLY_QUALIFIED_LU_ 
NAME 


(variable) 
MODE_NAME (variable) 
SYNC_LEVEL (variable) 
USER_ID (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation for which 
the attributes are desired. 
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Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_GET_ ATTRIBUTES return codes are: 


e PARAMETER _ CHECK 


— BAD _TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


—- BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


LU_ID indicates the identifier for the local LU under 
which the transaction program is executing. APPC/PC 
returns this value to the application subsystem of the 
transaction program when it defines the LU after the 
application subsystem issues ATTACH LU. For more 
information, see “ATTACH LU” on page 5-7. 


OWN_NET_NAME indicates the name (in EBCDIC) of 
the network containing the LU at which the local 
transaction program is located. 


OWN_LU_NAME indicates the network name (in 
EBCDIC) of the LU at which the local transaction 
program is located. 


PARTNER _LU_NAME indicates the name (in EBCDIC) 
of the LU at which the remote transaction program is 
located. The local LU uses this name to identify the 
remote LU when allocating a conversation. For more 
details, see the description of the LU_NAME parameter 
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of MC_ ALLOCATE under “MC_ALLOCATE” on 
page 6-13. 


PARTNER _FULLY_QUALIFIED_ LU_NAME 
indicates the fully qualified name (in EBCDIC) of the LU 
at which the remote transaction program is located. If 
APPC/PC does not know the partner’s fully-qualified LU 
name, it returns a null (0-length) value. 


MODE_NAME indicates the mode name (in EBCDIC) for 
the session on which APPC/PC allocated the 
conversation. 


SYNC_LEVEL indicates the level of synchronization 
processing that the programs are using for the 
conversation. The synchronization levels are NONE and 


CONFIRM. 


USER _ID indicates the user ID (in EBCDIC) if the 
program specified conversation-level security. An 
incoming ALLOCATE specifies this USER_ID when it 
requests the application subsystem to start a transaction 
program. If the program did not specify 
conversation-level security, or if the transaction program 
was initiated locally, APPC/PC returns a null (0-length) 
value for the USER_ID parameter. 


State Changes: 
None 
Notes: 


1. The program issues this verb to obtain the attributes 
of a conversation. 


2. The following parameters are returned in EBCDIC: 


OWN_NET_NAME 

OWN_LU_NAME 

PARTNER_LU_NAME 
PARTNER_LU_FULLY_QUALIFIED_ NAME 
MODE_NAME 

USER_ID in EBCDIC 
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You can use the CONVERT verb to convert these 
parameter values from ASCII to EBCDIC. 
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GET_TYPE 


Returns the conversation type (basic or mapped) of the 
specified conversation. A transaction program can use 
this verb for both basic conversations or mapped 
conversations. 


Supplied Parameters: 
GET_TYPE TP _ID (variable) 


CONV_ID (variable) 


Returned Parameters: 


RETURN_CODE (variable) 


TYPE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE _TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation for which 
the conversation type is desired. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The GET_TYPE return codes are: 


e PARAMETER_CHECK 


—- BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 
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For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_ BUSY 
APPC_DISABLED 
OK. 


TYPE indicates the conversation type. The conversation 
types are: 


e BASIC. CONVERSATION indicates that a basic 
conversation was initiated by one of the following 
methods: 


— The conversation was initiated with an 
ALLOCATE 
(CONV_TYPE=BASIC_ CONVERSATION) verb. 


— An incoming ALLOCATE specified a basic 
conversation. 


e MAPPED CONVERSATION indicates that a mapped 
conversation was initiated by one of the following 
methods: 


— The conversation was initiated with an 
MC_ALLOCATE verb. 


— The conversation was initiated with an 
ALLOCATE 
(CONV_TYPE=MAPPED CONVERSATION) 


verb. 


— An incoming ALLOCATE specified a mapped 
conversation. 


State Changes: 


None 
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Note: 


A program that APPC/PC can process at either the basic 
conversation API or the mapped conversation API uses 
this verb to determine which category of verbs, basic 
conversation or mapped conversation, to issue. 
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MC _ PREPARE _TO_ RECEIVE 


Changes a mapped conversation from send to receive state 
in preparation to receive data. Also performs the function 
of the MC_ FLUSH or MC_CONFIRM verbs. 


Supplied Parameters: 
MC_PREPARE_TO_RECEIVE TP_ID (variable) 


CONV_ID (variable) 


TYPE (SYNC_LEVEL) 
(FLUSH) 


LOCKS (SHORT) 
(LONG) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP _STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is preparing to receive data. 


TYPE specifies how APPC/PC prepares the conversation 
to receive data. 


e SYNC_LEVEL directs APPC/PC to prepare the 
conversation to receive data based on the 
synchronization level allocated to this conversation: 


— If SYNC_LEVEL is NONE, execute the function of 
the MC_FLUSH verb and then place the 
conversation in receive state. 
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— IfSYNC_LEVEL is CONFIRM, execute the 
function of the MC_CONFIRM verb (Gncluding 
flushing the local LU’s send buffer) and then place 
the conversation in receive state if the 
MC_CONFIRM function is successful (as indicated 
by a return code of OK with this 
MC_PREPARE TO RECEIVE verb). If the 
execution of the MC_ CONFIRM function is 
unsuccessful, the return code determines the state 
of the conversation. 


e FLUSH directs APPC/PC to flush the local LU’s send 
buffer before placing the conversation in receive state. 


LOCKS specifies when APPC/PC is to return control to 
the local program after executing the MC_CONFIRM 
function of this verb. APPC/PC ignores this parameter 
unless the verb also specifies TYPE(SSYNC_LEVEL) and 
the synchronization level for this conversation is 


CONFIRM. 


e SHORT directs APPC/PC to return control to the 
local transaction program after it receives an 
MC_CONFIRMED reply. With the short option, 
control is returned to the transaction program more 
quickly; however, more data flows on the line. 


e LONG informs APPC/PC that the MC_CONFIRMED 
reply is to be returned with any returned data that is 
available. With the LONG option, there is less line 
flow but APPC/PC takes longer to return control to 
the local transaction program. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
For detailed information on return codes listed below that 
do not include descriptions, see “Understanding Mapped 
Conversation Return Codes” on page 6-3 and 

Appendix C, “Verb Return Codes.” The 
MC_PREPARE TO RECEIVE return codes are: 


e PARAMETER_CHECK 
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—- BAD TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


—- P_TO_R_INVALID_TYPE: APPC/PC does not 
recognize the specified TYPE. 


e STATE_CHECK 


— P_TO R NOT_SEND STATE: The conversation 
is not in send state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
INCOMPLETE 

INCOMPLETE _ALTERED_ VERB 
OK. 


APPC/PC can report the following return codes if the 
program specifies TYPE(SYNC_LEVEL) and the 
synchronization level allocated to this conversation is 
CONFIRM. 


ALLOCATION_ERROR 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND 
PROG_ERROR_PURGING. 


State Changes: 


The conversation enters receive state when 
RETURN_CODE indicates OK. 
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For information on state changes when RETURN_CODE 
indicates other than OK, see “Understanding Mapped 
Conversation Return Codes” on page 6-3. 


Notes: 


1. The conversation for the remote transaction program 
enters send state when the remote transaction program 
issues an MC_ RECEIVE AND_ WAIT or 
MC_RECEIVE_IMMEDIATE verb and receives the 
SEND indication on the WHAT RECEIVED 
parameter. The remote transaction program can then 
send data to the local transaction program. 


2. If the local transaction program issues 
MC_PREPARE_ TO_RECEIVE with a SYNC_LEVEL 
of CONFIRM, the remote transaction program enters 
send state after issuing MC_CONFIRMED. 
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MC_RECEIVE_AND_ WAIT 


Waits for information to arrive on the specified 
conversation and then receives the information. If 
information is already available, the transaction program 
receives it without waiting. The information can be data, 
conversation status, or a request for confirmation. 
APPC/PC returns control to the transaction program and 
indicates the type of information received. 


The transaction program can issue this verb when the 
conversation is in either receive or send state. If the 
conversation is in send state, the LU first flushes its send 
buffer, sending all buffered information and the SEND 
indication to the remote transaction program. This action 
places the local.conversation in receive state. The LU 
then waits for information to arrive from the remote 
transaction program. The remote transaction program 
sends data to the local transaction program after it 
receives the SEND indication. 


Supplied Parameters: 
MC_RECEIVE_AND_WAIT | TP_ID (variable) 

CONV_ID (variable) 

DATA_PTR (variable) 


MAX LENGTH (variable) 
Returned Parameters: 


RETURN_CODE (variable) 
DATA_LENGTH (variable) 


DATA (see DATA_PTR) 


WHAT RECEIVED (variable) 


REQUEST_TO_SEND_RECEIVED 
(YES) 
(NO) 
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Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_ STARTED” on 
page 5-58. 


CONV _ID specifies the conversation ID of the 
conversation on which the local transaction program is to 
receive data. 


DATA_PTR specifies the address of the buffer that is to 
accept the received data. 


MAX LENGTH specifies the maximum amount of data 
(in bytes) that the program is to receive. Values between 
0 and 65535 are valid for this parameter, but the sum of 
this value and the offset portion of DATA PTR must not 
exceed 65535. This limit keeps the incoming data from 
crossing a segment boundary. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_RECEIVE_AND_WAIT return codes are: 


e PARAMETER _CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP _ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


—- DATA_AREA_ACROSS_SEGMENT: The data 


receiving area crosses a segment boundary. 
e STATE _CHECK 
— RCV_AND WAIT BAD STATE: The 


conversation is not in send or receive state. 
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For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_NORMAL 
DEALLOCATE_ABEND 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING. 


DATA _LENGTH indicates the actual amount of data the 
transaction program received up to the maximum 

(MAX LENGTH). The value of this variable is 0 if the 
program receives information other than data, or no 
information at all. 


DATA from the partner transaction program is received 
in the buffer specified by the address in the DATA PTR 
parameter. APPC/PC does not place any information in 
this buffer when the program receives information other 
than data, as indicated by the WHAT_ RECEIVED 
parameter. 


WHAT_RECEIVED indicates what the transaction 
program received. The transaction program should 
examine this variable only when RETURN_CODE 
indicates OK. APPC/PC does not place any information 
in this variable when RETURN_ CODE indicates other 
than OK. 


e DATA COMPLETE indicates that the transaction 


program has received a complete data record, or the 
last remaining portion of a data record. 
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DATA INCOMPLETE indicates that the transaction 
program has received an incomplete data record. The 
transaction program can issue another 
MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_IMMEDIATE (or more than one) to 
receive the remaining data. 


SEND indicates that the remote transaction program 
has entered receive state, thereby placing the local 
transaction program in send state. After receiving the 
SEND indication, the local transaction program can 
issue the MC_SEND_ DATA verb to send data to the 
remote program. 


CONFIRM indicates that the remote transaction 
program has issued MC_CONFIRM, requesting the 
local transaction program to respond by issuing 
MC_CONFIRMED. The program may respond, 
instead, by issuing MC_SEND_ERROR. 


CONFIRM_SEND indicates that the remote 
transaction program has issued 
MC_PREPARE_TO_RECEIVE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing MC_CONFIRMED or 
MC_SEND_ERROR. 


CONFIRM DEALLOCATE indicates that the remote 
transaction program has issued MC_DEALLOCATE 
with TYPE(SYNC_LEVEL), and the synchronization 
level is CONFIRM. The local transaction program can 
respond by issuing MC_CONFIRMED or 
MC_SEND_ERROR. 


REQUEST _TO_SEND_RECEIVED indicates whether 
the local LU has received a REQUEST_TO SEND. The 
indication is either YES or NO. 


YES indicates that the local LU has received a 
REQUEST _TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued MC_REQUEST_TO_SEND, requesting the 
local transaction program to enter receive state and 
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thereby place the remote transaction program in send 
state. 


NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification from the remote 
transaction program. 


State Changes: 


The following state changes occur when the 
RETURN_CODE parameter indicates OK. For 
information on state changes when RETURN_CODE 
indicates other than OK, see “Understanding Mapped 
Conversation Return Codes” on page 6-3. 


The conversation enters receive state when the verb is 
issued in send state and WHAT RECEIVED indicates 
DATA COMPLETE or DATA INCOMPLETE. 


The conversation enters send state when 
WHAT_ RECEIVED indicates SEND. 


The conversation enters confirm state when 
WHAT RECEIVED indicates CONFIRM, 
CONFIRM_SEND, or CONFIRM _DEALLOCATE. 


No state change occurs when the transaction program 
issues MC_ RECEIVE _AND_ WAIT in receive state 
and WHAT RECEIVED indicates 

DATA COMPLETE or DATA_ INCOMPLETE. 


Notes: 


1. 


When the transaction program issues 
MC_RECEIVE_AND_ WAIT in send state, the LU 
implicitly executes an MC_ PREPARE TO RECEIVE 
with TYPE(FLUSH) before executing the 
MC_RECEIVE_ AND WAIT. See the description of 
MC_PREPARE TO_RECEIVE for details of this 
function. 


The mapped conversation protocol boundary provides 
for sending and receiving only data records. Unlike 
the logical records defined for the basic conversation 
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protocol boundary, data records contain only data; 
they do not contain the logical record length field. 


The MC RECEIVE _AND_ WAIT verb can receive 
only as much of the data record as the program 
specifies using the MAX LENGTH parameter. The 
WHAT_RECEIVED parameter indicates whether the 
transaction program has received a complete or 
incomplete data record, as follows: 


e The WHAT RECEIVED parameter indicates 
DATA COMPLETE after the transaction program 
receives a complete data record or the last portion 
of a data record. The length of the record (or 
portion of the record) is equal to (or less than) the 
length specified on the MAX LENGTH parameter. 


e The WHAT RECEIVED parameter indicates 
DATA INCOMPLETE after the transaction 
program receives a portion of a data record other 
than the last remaining portion. APPC/PC detects 
that the data record is incomplete because the 
remaining length of the record is greater than the 
length specified on the MAX LENGTH parameter. 
The amount received equals the length specified. 
The transaction program must issue another. 
MC_RECEIVE_AND_WAIT (or possibly more 
than one) to receive the rest of the data record. 


A program can use MC_RECEIVE_AND_ WAIT with 
MAX LENGTH(0) to determine the type of 
information that is available without actually 
receiving data. The RETURN_CODE and 

WHAT RECEIVED parameters provide this 
information as usual. However, the transaction 
program receives no data in this case. 


. The transaction program receives only one kind of 


information at a time. For example, it may receive 
data or a CONFIRM request, but it cannot receive 
both at the same time. The RETURN_CODE and 
WHAT _RECEIVED parameters indicate to the 
program the kind of information the program receives. 
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6. The local transaction program usually receives a 
REQUEST_TO_SEND notification when it is in send 
state. APPC/PC reports this request to the local 
transaction program on an MC_SEND_ DATA verb or 
an MC_SEND_ERROR verb issued in send state. 
However, the local transaction program can receive 
notification when the program is in receive state in 
the following cases: 


e When the local transaction program just entered 
receive state and the remote transaction program 
issues MC_ REQUEST _TO_SEND before it enters 
send state. 


e When the remote transaction program has just 
entered receive state by using the 
MC_PREPARE_ TO_ RECEIVE verb (not 
MC_RECEIVE_AND_ WAIT), and then issuing 
MC_REQUEST_TO_SEND before the local 
transaction program responds by entering send 
state. This ambiguity can occur because 
MC_REQUEST_TO_SEND is an expedited request 
and this request can, therefore, arrive ahead of the 
request carrying the SEND indication. 


The local transaction program might not be able to 
distinguish this case from the preceding case. The 
remote transaction program can avoid this 
ambiguity by waiting until it receives information 
from the local transaction program before it issues 


the MC_REQUEST_TO_SEND. 


e The remote program issues the 
MC_REQUEST_TO_SEND in send state. 
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MC_RECEIVE_ IMMEDIATE 


Receives information that is available from the specified 
mapped conversation, but does not wait for information to 
arrive. The information (if any) can be data, conversation 
status, or a request for confirmation. APPC/PC returns 
control to the transaction program with an indication of 
whether information was received and, if so, the type of 
information. 

Supplied Parameters: 

MC_RECEIVE_IMMEDIATE | TP_ID (variable) 
CONV_ID (variable) 
DATA_PTR (variable) 


MAX_LENGTH (variable) 
Returned Parameters: 


RETURN_CODE (variable) 
DATA_LENGTH (variable) 
DATA (see DATA_PTR) 


WHAT_RECEIVED (variable) 


REQUEST_TO_SEND_RECEIVED 
(YES) 


(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is to receive data. 
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DATA_PTR specifies the address of the data buffer that 
is to accept the received data. 


MAX LENGTH specifies the most data (in bytes) the 
program is to receive when APPC/PC executes this verb. 
Values between 0 and 65535 are valid for this parameter 
but the sum of this value and the offset portion of 
DATA_PTR must not exceed 65535. This limit keeps the 
incoming data from crossing a segment boundary. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_RECEIVE IMMEDIATE return codes are: 


e PARAMETER_CHECK 


— BAD TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


- BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— DATA_AREA ACROSS SEGMENT: The data 
receiving area crosses a segment boundary. 


e STATE_CHECK 


— RCV_IMMD NOT_RCV_STATE: The 
conversation is not in receive state. 


a, UNSUCCESSFUL: No data was available to be 
received. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
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CONV_FAILURE_RETRY 
DEALLOCATE_NORMAL 
DEALLOCATE_ABEND 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING. 


DATA_LENGTH indicates the actual amount of data the 
transaction program received up to the maximum 

(MAX LENGTH). If the program receives information 
other than data, or no information at all, this variable is 
0. 


DATA from the partner transaction program is received 
in the buffer that the DATA PTR parameter specifies. 
When the program receives information other than data, 
as indicated by the WHAT RECEIVED parameter, 
APPC/PC does not place any information in this buffer. 


WHAT_RECEIVED indicates what kind of information 
the transaction program received. The program should 
examine this variable only if the RETURN_CODE 
parameter indicates OK. APPC/PC does not place any 
information in this variable if the RETURN_CODE is 
other than OK. The WHAT RECEIVED indications are: 


e DATA COMPLETE indicates that the transaction 
program has received a complete data record, or the 
last portion of a data record. 


e DATA INCOMPLETE indicates that the transaction 
program has received less than a complete data record. 
The transaction program can issue another 
MC_RECEIVE_IMMEDIATE or 
MC_RECEIVE_AND_ WAIT (or possibly more than 


one) to receive the remaining data. 


e CONFIRM indicates that the remote transaction 
program has issued MC_CONFIRM, requesting the 
local transaction program to respond by issuing 
MC_CONFIRMED. The program can respond by 
issuing MC_CONFIRMED or MC_SEND_ERROR. 
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CONFIRM_SEND indicates that the remote 
transaction program has issued 
MC_PREPARE_TO_RECEIVE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing MC_CONFIRMED or 
MC_SEND_ ERROR. 


CONFIRM_DEALLOCATE indicates that the remote 
transaction program has issued MC_DEALLOCATE 
with TYPE(SYNC_LEVEL), and the synchronization 
level is CONFIRM. The local transaction program can 
respond by issuing MC_CONFIRMED or 
MC_SEND_ERROR. 


SEND indicates that the remote transaction program 
has entered receive state, placing the local transaction 
program in send state. After receiving the SEND 
indication, the local transaction program can issue the 
MC_SEND_ DATA verb to send data to the remote 
transaction program. 


REQUEST_TO_SEND_RECEIVED indicates whether 
the local LU has received a REQUEST_TO_SEND from 
the remote transaction program. The indication is either 
YES or NO. 


YES indicates that the local LU has received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued MC_REQUEST_TO_SEND, requesting the 
local transaction program to enter receive state and 
thereby place the remote transaction program in send 
state. 


NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification. 


State Changes: 


The following state changes occur when the 
RETURN_CODE parameter indicates OK. For 
information on state changes when RETURN_CODE 
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indicates other than OK, see “Understanding Mapped 
Conversation Return Codes” on page 6-3. 


The conversation enters send state when 


WHAT_RECEIVED indicates SEND. 


The conversation enters confirm state when 
WHAT _ RECEIVED indicates CONFIRM, 
CONFIRM_SEND, or CONFIRM _DEALLOCATE. 


No state change occurs when the transaction program 
issues MC_ RECEIVE IMMEDIATE and 
WHAT_RECEIVED indicates DATA_COMPLETE or 
DATA _ INCOMPLETE. 


Notes: 


1. 


The mapped conversation API provides for sending and 
receiving data records only. Unlike the logical records 
defined for the basic conversation API, data records 
contain only data; they do not contain the logical 
record length field. 


The MC_RECEIVE_IMMEDIATE verb can receive 
only as much of the data record as the transaction 
program specifies using the MAX LENGTH 
parameter. The WHAT RECEIVED parameter 
indicates whether the program has received a complete 
or incomplete data record, as follows: 


e The WHAT RECEIVED parameter indicates 
DATA COMPLETE after the transaction program 
receives a complete data record or the last 
remaining portion of a data record. The length of 
the record (or portion of the record) is equal to (or 
less than) the length specified on the 
MAX _ LENGTH parameter. 


e The WHAT RECEIVED parameter indicates 
DATA INCOMPLETE after the transaction 
program receives part of a data record other than 
the last portion. The program issues another 
MC_RECEIVE_IMMEDIATE (or possibly more 
than one) to receive the rest of the data record. 
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3. 


5. 


A program can use MC_RECEIVE_IMMEDIATE with 
MAX _ LENGTH(0) to determine the type of 
information that is available without actually 
receiving data. The RETURN_CODE and 
WHAT _ RECEIVED parameters provide this 
information, as usual. However, the program receives 
no data in this case. 


The transaction program receives only one kind of 
information at a time. For example, it may receive 
data or a CONFIRM request, but it cannot receive 
both at the same time. The RETURN_CODE and 
WHAT_RECEIVED parameters indicate to the 
program the kind of information the program receives. 


The local transaction program usually receives a 
REQUEST _TO_SEND notification when it is in send 
state. APPC/PC reports this request to the local 
transaction program in the RETURN_CODE of an 
MC_SEND_DATA verb or an MC_SEND_ERROR 
verb that the local transaction program issues in send 
state. However, the local transaction program can 
receive the notification when the program is in receive 
state in the following cases: 


e When the local transaction program just entered 
receive state and the remote transaction program 
issues MC_ REQUEST _TO_SEND before it enters 
send state. 


e When the remote transaction program has just 
entered receive state by issuing the 
MC_PREPARE TO _RECEIVE verb (not 
MC_RECEIVE_AND_WAIT), and then issuing 
MC_REQUEST_TO_SEND before the local 
transaction program responds by entering send 
state. This ambiguity can occur because 
MC_REQUEST_TO_SEND is an expedited request 
and this request can arrive ahead of the request 
carrying the SEND indication. 


The local transaction program might not be able to 
distinguish this case from the preceding case. The 
remote transaction program can avoid this 
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ambiguity by waiting until it receives information 
from the local transaction program before it issues 


the MC_REQUEST_ TO_SEND. 


When the remote transaction program issues the 
MC_REQUEST_TO_SEND in send state. 
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MC_REQUEST_TO_SEND 


Notifies the remote transaction program that the local 
transaction program is requesting to enter send state for 
the mapped conversation. APPC/PC places the mapped 
conversation in send state when the local transaction 
program subsequently receives a SEND indication from 
the remote transaction program 


Supplied Parameters: 
MC_REQUEST_TO_SEND TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is requesting to send data. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC_REQUEST_TO_SEND return codes are: 


e PARAMETER CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD_CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 
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STATE_CHECK 


— R T S NOT_RCV_STATE: The conversation is 
not in receive or confirm state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


None 


Notes: 


1. 


A transaction program enters receive state by issuing 
the MC_RECEIVE_AND_WAIT verb or the 
MC_PREPARE_ TO RECEIVE verb. The partner 
transaction program enters the corresponding send 
state when it issues an MC_RECEIVE AND _WAIT 
or MC_RECEIVE_ IMMEDIATE verb and receives the 
SEND indication (on the WHAT _RECEIVED 
parameter). 


The REQUEST _TO_ SEND_RECEIVED indication of 
YES is normally given to the remote transaction 
program when the conversation is in send state; that 
is, on an MC_SEND_DATA verb or on an 
MC_SEND_ERROR verb issued in send state. 
However, the YES indication can also be given on an 
MC_RECEIVE_AND_WAIT or 
MC_RECEIVE_IMMEDIATE verb. For more 
information, see “MC_RECEIVE AND_ WAIT” on 
page 6-46 or “MC_RECEIVE_IMMEDIATE” on 
page 6-53. 


When the remote LU receives the 
MC_REQUEST_TO_SEND notification, it retains the 
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notification until the remote transaction program 
issues a verb with the 


REQUEST_TO_SEND_RECEIVED parameter. 


The remote LU retains only one 
MC_REQUEST_TO_SEND notification at a time (for 
each conversation). The remote LU discards 
additional notifications until the LU can indicate the 
retained notification to the remote transaction 
program. Therefore the local transaction program can 
issue the MC_ REQUEST_TO_SEND verb more times 
than the remote LU indicates to the remote 
transaction program. 
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MC_SEND_DATA 


Sends one data record to the remote transaction program. 
The data format consists entirely of data. 


Supplied Parameters: 
MC_SEND_DATA TP_ID (variable) 


CONV_ID (variable) 
DATA_LENGTH (variable) 


DATA (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 
the local transaction program is sending the data. 


DATA_LENGTH specifies the length of the data record 
to be sent. The length of the data record can range from 0 
to 65535 bytes. The local LU sends a null data record if 
the local transaction program specifies a data record 
length of 0. The sum of the DATA LENGTH value and 
the offset portion of the DATA address cannot exceed 
65535. This limit keeps the data from crossing a segment 
boundary. 


DATA specifies the data record that the local transaction 
program is sending. 
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Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The MC _SEND_ DATA return codes are: 


e PARAMETER _CHECK 


— BAD TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— DATA AREA ACROSS SEGMENT: The data to 
be sent crosses a segment boundary. 


e STATE_CHECK 


— SEND DATA NOT SEND STATE: The 
conversation is not in send state. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_PURGING. 


REQUEST_TO SEND_ RECEIVED indicates whether 
the local LU has received a REQUEST_TO_SEND 
notification. The indication is either YES or NO. 


e YES indicates that the local LU has received a 
REQUEST_TO_SEND notification from the remote 
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transaction program. The remote transaction program 
issues MC_ REQUEST_TO_ SEND to request the local 
transaction program to enter receive state and place 
the remote transaction program in send state. 


e NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification. 


State Changes: 


The state does not change when the RETURN_CODE 
indicates OK. 


For information on state changes when the 
RETURN_CODE indicates other than OK, see 
“Understanding Mapped Conversation Return Codes” on 
page 6-3. 


Notes: 


1. The mapped conversation API provides for sending and 
receiving data records only. Unlike the logical records 
defined for the basic conversation API, data records 
contain only data; they do not contain the logical 
record length field. 


2. The MC_SEND_DATA verb sends a complete data 
record. The sending program, therefore, cannot 
truncate a data record. 


3. The local LU stores in a send buffer the data the local 
transaction program is sending. The local LU sends 
the data to the remote LU when the send buffer 
accumulates enough data for transmission. The local 
transaction program can force the LU to flush its send 
buffer by issuing the MC_FLUSH verb. The amount 
of data that is enough for transmission depends on the 
characteristics of the session allocated for the mapped 
conversation, and can vary from session to session. 


4, When REQUEST_TO SEND_RECEIVED indicates 
YES, the remote transaction program is requesting the 
local transaction program to enter receive state and 
thereby place the remote transaction program in send 
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state. A transaction program uses the 
MC_RECEIVE_ AND_ WAIT verb or the 
MC_PREPARE_ TO_RECEIVE verb to enter receive 
state. The partner transaction program enters send 
state when it issues an MC_ RECEIVE AND WAIT 
or MC_RECEIVE_ IMMEDIATE verb and receives the 
SEND indication on the WHAT _RECEIVED 
parameter. 
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MC_SEND_ERROR 


Informs the remote transaction program that the local 
transaction program found an error. If the conversation 
is in send state, the local LU flushes its send buffer. 


After the successful completion of this verb, the local 
transaction program is in send state and the remote 
transaction program is in receive state. The transaction 
program must take the appropriate actions to correct the 
problem. 


Supplied Parameters: 
MC_SEND_ERROR TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameters, 
see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is sending the error. 


Returned Parameters: 
RETURN_CODE indicates the result of verb execution. 
APPC/PC returns the following MC_SEND_ERROR 


return codes independently of the state of the 
conversation: 
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e PARAMETER CHECK 


— BAD TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— DATA_AREA_ACROSS_SEGMENT: The data to 
be sent crosses a segment boundary. 


For detailed information on return codes listed below, 
see “Understanding Mapped Conversation Return 
Codes” on page 6-3 and Appendix C, “Verb Return 
Codes.” 


— APPC_ABENDED 

— APPC_BUSY 

— APPC_DISABLED 

— CONV_FAILURE_NO_RETRY 
— CONV_FAILURE_RETRY 

— CONVERSATION_TYPE_MIXED 
— INCOMPLETE | . 

— INCOMPLETE_ALTERED_VERB 
— OK. 


If the transaction program issues MC_SEND_ERROR in 
send state, APPC/PC can report the following return 
codes: 


e ALLOCATION ERROR 
e DEALLOCATE_ABEND 
e PROG_ERROR_PURGING. 


If the transaction program issues MC_SEND_ ERROR in 
receive state, APPC/PC can report the following return 
code: 


e DEALLOCATE NORMAL: The remote transaction 
program issued a DEALLOCATE specifying the 
TYPE(SYNC_LEVEL) where the SYNC_LEVEL of 
the conversation is NONE or TYPE(FLUSH) 
parameter. This return code does not indicate an error 
condition. 
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REQUEST_TO_ SEND_RECEIVED indicates whether 
the local LU has received a REQUEST_TO_ SEND 
notification. The indication is either YES or NO. 


e YES indicates that the local LU has received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued MC_REQUEST_TO_SEND, requesting the 
local transaction program to enter receive state and 
thereby place the remote transaction program in send 
state. 


e NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification. 


State Changes: 


The following state changes occur when the 
RETURN_CODE parameter indicates OK. For 
information on state changes when the RETURN_CODE 
indicates other than OK, see “Understanding Mapped 
Conversation Return Codes” on page 6-3. 


The conversation enters send state after the local 
transaction program issues MC_SEND_ ERROR in 
receive or confirm state. 


No state change occurs when the local transaction 
program issues the verb in send state. 


Notes: 


1. The local transaction program can ensure that the 
remote transaction program receives the complete 
error notification as soon as possible by issuing 
MC_FLUSH immediately after MC_SEND_ERROR. 


2. An MC_SEND_ ERROR is reported to the remote 
transaction program as one of the following return 
codes: 


e PROG_ERROR NO_TRUNC: The local 
transaction program issued MC_SEND_ERROR in 
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send state. No data truncation occurs at the 
mapped conversation API. 


e PROG_ERROR PURGING: The local transaction 
program issued MC_SEND_ERROR in receive 
state and all data sent by the remote transaction 
program and not yet received by the local 
transaction program is purged. This return code 
can also occur if the local transaction program 
issued MC_SEND_ERROR in confirm state, in 
which case no data is purged. 


3. When a transaction program issues 
MC_SEND_ERROR in receive state, all incoming 
information is purged. The incoming information that 
is purged includes the following return code 
indications: 


e ALLOCATION_ERROR 
e DEALLOCATE_ABEND 
e PROG_ERROR_PURGING. 


APPC/PC reports the DEALLOCATE_ NORMAL 
return code instead of ALLOCATION _ERROR or 
DEALLOCATE ABEND. It reports OK instead of 
PROG_ERROR_PURGING. 


The other kinds of incoming information that are 
purged are: 


e Data sent by a transaction program issuing the 
MC_SEND_DATA verb. 


e Confirmation requests sent by a transaction 
program issuing the MC_CONFIRM verb. 


If a transaction program sends a confirmation request 
in conjunction with the MC_DEALLOCATE verb by 
specifying the TYPE(SYNC_LEVEL) parameter, then 
the deallocation request is also purged. 


However, incoming REQUEST_TO_ SEND indications 
are not purged. 
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4. When the returned 
REQUEST_TO_SEND_RECEIVED parameter 
indicates YES, the remote transaction program is 
requesting the local transaction program to enter 
receive state and thereby place the remote program in 
send state. A transaction program enters receive state 
by issuing the MC_RECEIVE_AND_WAIT or 
MC_PREPARE TO_RECEIVE verb. 


The partner transaction program enters send state 
when it issues an MC RECEIVE AND WAIT or 
MC_RECEIVE_IMMEDIATE verb and receives the 
SEND indication on the WHAT_RECEIVED 
parameter. 


5. The local transaction program can use 
MC_SEND_ERROR for various application-level 
functions. For example, the local transaction program 
can issue this verb to inform the remote transaction 
program of an error it found in the data records it 
received, or to reject a confirmation request. 
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MC_TEST 


Tests the specified conversation to determine if the local 
LU has received a REQUEST_TO_SEND notification 
from a remote transaction program. The return code 
indicates the result of the test. 


Supplied Parameters: 
MC_TEST TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation the local 
transaction program is checking for a 
REQUEST _TO_ SEND indication. 


Returned Parameters: 


RETURN_ CODE indicates the result of the test. The 
MC_TEST return codes are: 


e OK: The local LU has received a 
REQUEST_TO_SEND notification. The remote 
program has issued MC_ REQUEST_TO_SEND, 
requesting the local program to enter receive state and 
thereby place the remote program in send state. 


e PARAMETER CHECK 
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— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD_CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


UNSUCCESSFUL: The local LU has not received a 
REQUEST_TO_ SEND notification. 


For detailed information on the following return codes, 
see “Understanding Mapped Conversation Return Codes” 
on page 6-3 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB. 


State Changes: 


None 


Notes: 


1. 


When the local LU receives a REQUEST_TO_SEND 
notification, the remote transaction program is 
requesting the local transaction program to enter 
receive state and thereby place the remote transaction 
program in send state. A transaction program enters 
receive state by issuing the 
MC_RECEIVE_AND_WAIT or 
MC_PREPARE_ TO _RECEIVE verb. 


The partner transaction program enters send state 
after it issues an MC RECEIVE _AND_ WAIT or 
MC_RECEIVE_IMMEDIATE verb and then receives 
the SEND indication on the WHAT RECEIVED 
parameter. 
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Chapter 7. Using Transaction 
Basic Conversation Verbs 


This chapter describes the category of verbs called basic 
conversation verbs that are available for use by 
transaction programs. Basic conversation verbs define the 
basic conversation API for end-user program-to-program 
support. 


Before the detailed descriptions of the basic conversation 
verbs is a discussion of the conversation states at the 
basic conversation API, and a description of the basic 
conversation return codes. These subjects apply generally 
to all of the basic conversation verbs. 


Note: 


Every conversation is either a basic or a mapped 
conversation. A transaction program cannot use the basic 
conversation verbs and mapped conversation verbs on the 
same conversation. However, a transaction program 
providing its own mapped conversation layer can use a 
basic conversation to perform mapped conversation 
operations. 
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Understanding Basic 
Conversation States 


The selection of verbs that a program can issue for a 
particular conversation depends on the state of the 
conversation. As the program issues verbs, the state of 
the conversation can change. This state change occurs in 
response to a verb issued by the local program, a verb 
issued by the remote program, or as a result of network 
errors. 


APPC/PC defines the state of a conversation in terms of 
the local program’s view of the local end of the 
conversation. The local end of the conversation is the end 
to which the local program is connected. The states of 
other conversations allocated to the program can be 
different. For example, one conversation can be in 
receive state and another in send state, concurrently. 


The state of the basic conversation determines which 
verbs APPC/PC allows a program to issue. The folowing 
table correlates the verbs, and parameters if applicable, to 
the basic conversation states. 


7-2 


Conversation States at 
Basic Conversation 
Protocol Boundary 


Verb 


DEALLOCATE with n/a Yes No No 
TYPE(FLUSH) or 
TYPE(SYNC_LEVEL) 

DEALLOCATE with 


TYPE(ABEND_ PROG), 
TYPE(ABEND_ SVC), or 
TYPE(ABEND_ TIMER) 


nla 


TEST with 
TEST(REQUEST_TO_ 
SEND_RECEIVED) 


WAIT 


At the intersection of each verb row and state column, the 
table indicates Yes, No, or n/a. Yes means that APPC/PC 
allows the program to issue the verb when the 
conversation is in that state. 


No means the program cannot issue the verb because 
APPC/PC disallows the verb in that state. APPC/PC 
treats a verb issued for a conversation in a disallowed 
state as a state-check condition and issues an appropriate 
return code. The individual verb descriptions list the 
applicable state-check conditions. 
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n/a means the state is not applicable either because it 
cannot exist when the verb is issued or because the state 
is not relevant to the verb. 


A conversation enters a particular state when the 
transaction program issues a verb that causes a state 
transition or when the program receives a return code 
that indicates that a state transition has occurred. This 
chapter defines the specific state transitions under the 
following heading, “Understanding Basic Conversation 
Return Codes,” and in each verb description under the 
headings “Returned Parameters” and “State Changes.” 
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Understanding Basic 
Conversation Return Codes 


All conversation verbs have a parameter called 
RETURN_CODE that APPC/PC uses to pass a return 
code back to the program when the LU finishes executing 
a verb. The return code indicates the result of verb 
execution, including any state changes to the specified 
basic conversation. For information on which verbs a 
program can issue in each state, see “Understanding Basic 
Conversation States” on page 7-2. 


The structure of a return code is a 2-byte primary code 
that identifies the error type, and a 4-byte secondary code 
that provides more detailed error information. 


Some of the return codes indicate results of the local LU’s 
processing of a verb; APPC/PC returns these return codes 
on the verb that initiated the local processing. Other 
return codes indicate results of processing initiated at the 
remote end of the conversation. 


Depending on the verb, APPC/PC returns these codes on 
the verb that initiated the remote processing or on a later 
verb. Still other return codes report events occurring at 
the remote end of the conversation. In any case, 
APPC/PC returns only one code at a time. 


The following return codes can be returned on one or 
more basic conversation verbs: 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DATA_POSTING_BLOCKED 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
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DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_ VERB 
INVALID_VERB 

OK 
POSTING_NOT_ACTIVE 
PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


Detailed descriptions of these return codes follow. Brief 
references to these return codes appear in the individual 
verb descriptions later in this chapter. For a description 
of unique parameters or return codes, see the individual 

verb descriptions. 


ALLOCATION_ERROR indicates that the local 
transaction program issued an ALLOCATE and APPC/PC 
could not complete the allocation of the specified 
conversation. The ALLOCATION ERROR indication and 
one of the following secondary return codes form the 
complete return code that APPC/PC returns to the 
transaction program; the secondary return code identifies 
the specific error. 


The remote LU and the remote transaction program 
referred to in the following secondary return code 
definitions are the LU specified in the LU_NAME 
parameter and the program specified in the TPN 
parameter, respectively, of the ALLOCATE verb. 


APPC/PC reports allocation errors caused by the local LU 
failing to obtain a session for the conversation on the 
ALLOCATE verb, and by the remote LU rejecting the 
allocation request on a subsequent verb. When APPC/PC 
returns an ALLOCATION_ERROR to the transaction 
program, it places the basic conversation in reset state. 


The ALLOCATION ERROR secondary return codes are 
as follows: 
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ALLOCATION_FAILURE_NO_RETRY indicates 
that APPC/PC cannot allocate the basic conversation 
on a session because of a permanent condition. For 
example, APPC/PC cannot activate the session to be 
used for the basic conversation because the current 
mode session limit for the specified partner LU is 0; 
because of a system definition error or a 
session-activation protocol error; or because APPC/PC 
deactivated the session in response to a session 
protocol error before it could allocate the basic 
conversation. The transaction program should not try 
the allocation request again until the condition is 
corrected. 


ALLOCATION_FAILURE_RETRY indicates that 
APPC/PC cannot allocate the basic conversation on a 
session because of a temporary condition. For 
example, APPC/PC cannot allocate the session for the 
basic conversation because of a temporary lack of 
sessions at the local LU or remote LU. The error can 
also occur if APPC/PC deactivates the session because 
of a line or modem failure before it could allocate the 
conversation. 


The condition is temporary; the transaction program 
can try the allocation request again. However, to 
avoid congesting the network with attempted 
allocation requests, the transaction program should 
pause or wait for a keystroke before retrying the 
transaction. 


CONVERSATION_TYPE_MISMATCH indicates 
that the remote LU rejects the allocation request 
because the remote transaction program does not 
support basic conversations. APPC/PC returns this 
return code on a subsequent verb. 


PIP_NOT_ALLOWED indicates that the remote LU 
rejects the allocation request because the local 
program specified program initialization parameters 
(by setting the PIP_DATA LENGTH parameter to a 
non-0 value) and either the remote LU does not 
support PIP data, or the remote transaction program 
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has no PIP variables defined. APPC/PC returns this 
return code on a subsequent verb. 


PIP_NOT_SPECIFIED CORRECTLY indicates 
that the remote LU rejects the allocation request 
because the remote transaction program has one or 
more PIP variables defined and the local transaction 
program has specified that there are no program 
initialization parameters (by setting the 

PIP_DATA_ LENGTH parameter of the ALLOCATE 
verb to 0). 


This error can also indicate that the local transaction 
program has not specified program initialization 
parameters (by setting the PIP_DATA LENGTH 
parameter to a non-0 value) that do not correspond in 
number to those defined for the remote transaction 
program. APPC/PC returns this return code on a 
subsequent verb. 


SECURITY_NOT_VALID indicates that the remote 
LU rejects the allocation request because access 
security information (specified using the ALLOCATE 
SECURITY parameter) is invalid. APPC/PC returns 
this return code on a subsequent verb. 


SYNC_LEVEL_NOT_SUPPORTED indicates that 
the remote LU rejects the allocation request because 
the local program specified a synchronization level 
(using the SYNC_LEVEL parameter) that the remote 
program does not support. APPC/PC returns this 
return code on a subsequent verb. 


TPN _NOT_RECOGNIZED indicates that the remote 
LU rejects the allocation request because the local 
transaction program specified a remote transaction 
program name that the remote LU does not recognize. 
APPC/PC returns this return code on a subsequent 
verb. 


TRANS _PGM_NOT_AVAIL_NO_RETRY indicates 
that the remote LU rejects the allocation request 
because the local transaction program specified a 
remote transaction program that the remote LU 


recognizes but cannot start. The condition is 
permanent; the transaction program should not try the 
allocation request again. APPC/PC returns this return 
code on a subsequent verb. 


e TRANS PGM_NOT_AVAIL_ RETRY indicates that 
the remote LU rejects the allocation request because 
the local transaction program specified a remote 
transaction program that the remote LU recognizes but 
currently cannot start. The condition is temporary; 
the transaction program can try the conversation 
again. APPC/PC returns this return code on a 
subsequent verb. 


APPC_ABENDED indicates that APPC/PC has been 
abnormally terminated. 


APPC_ BUSY indicates that APPC/PC is currently 
executing another verb and cannot execute this verb. 
This error can occur if a verb is issued after APPC/PC 
execution is interrupted (for example, by a Ctrl-Break or 
timer interrupt). 


APPC_DISABLED indicates that APPC/PC is disabled 
as a result of the DISABLE/ENABLE_APPC verb. 


CONVERSATION_TYPE_MIXED indicates that the 
local program issued a combination of basic conversation 
verbs and mapped conversation verbs on the same 
conversation. APPC/PC reports this return code on the 
verb issued. 


CONV_FAILURE NO_RETRY indicates that a failure 
occurred that caused APPC/PC to terminate the 
conversation prematurely. For example, APPC/PC 
deactivated the session that the transaction programs 
were using for the conversation because of a session 
protocol error. The condition is permanent; the 
transaction program should not try the transaction again 
until the condition is corrected. APPC/PC can report this 
return code to the local transaction program on a verb the 
program issues in any state other than reset. APPC/PC 
leaves the conversation in reset state. 
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CONV_FAILURE_RETRY indicates that a failure 
occurred that caused APPC/PC to terminate the 
conversation prematurely. For example, APPC/PC 
terminates conversations when it must deactivate the 
associated sessions in response to a line or modem failure. 
The condition is temporary; the transaction program can 
try the conversation again. However, to avoid congesting 
a network with attempted allocation requests, the 
transaction program should pause or wait for a keystroke 
before retrying the transaction. APPC/PC can report this 
return code to the local program on a verb that the 
program issues in any state other than reset. APPC/PC 
places the conversation in reset state. 


DATA _POSTING_BLOCKED indicates that a 
transaction program issued a WAIT or TEST verb and 
APPC/PC cannot post one of the active conversations 
because the APPC/PC workspace storage assigned to a 
session is filled, and the transaction program is unable to 
send a pacing response. The condition can be corrected 
by issuing a RECEIVE_IMMEDIATE or 

RECEIVE _AND_WAIT on one of the conversations 
specified in the TEST or WAIT verb. APPC/PC reports 
this return code only if receive pacing is active. 


DEALLOCATE ABEND_ PROG indicates that the 
remote transaction program issued a DEALLOCATE verb 
specifying the TYPE(ABEND_PROG) parameter. The 
remote LU can also issue a DEALLOCATE verb 
specifying the TYPE(ABEND_PROG) parameter in 
response to a remote transaction program abnormal 
termination condition. If the conversation for the remote 
transaction program is in receive state when the remote 
transaction program or LU issues a DEALLOCATE verb, 
information sent by the local transaction program and not 
yet received by the remote transaction program is purged. 


APPC/PC returns the DEALLOCATE_ABEND_ PROG 
return code to the local transaction program on a verb the 
program issues in either send or receive state. After 
APPC/PC issues this return code, it deallocates the 
conversation, making the conversation unavailable to the 
program. 
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DEALLOCATE ABEND_ SVC indicates that the remote 
transaction program issued a DEALLOCATE verb 
specifying the TYPE(ABEND_SVC) parameter. If the 
conversation for the remote transaction program is in 
receive state when the remote transaction program issues 
a DEALLOCATE verb, information sent by the local 
transaction program and not yet received by the remote 
transaction program is purged. 


APPC/PC returns the DEALLOCATE_ABEND_SVC 
return code to the local transaction program on a verb the 
program issues in either send or receive state. After 
APPC/PC issues this return code, it deallocates the 
conversation, making the conversation unavailable to the 
program. 


DEALLOCATE ABEND_ TIMER indicates that the 
remote transaction program issued a DEALLOCATE verb 
specifying the TYPE(ABEND_ TIMER) parameter. If the 
conversation for the remote transaction program is in 
receive state when the program issues a DEALLOCATE 
verb, information sent by the local transaction program 
and not yet received by the remote transaction program is 
purged. 


APPC/PC returns the DEALLOCATE_ABEND_ TIMER 
return code to the local transaction program on a verb the 
program issues in either send or receive state. After 
APPC/PC issues this return code, it deallocates the 
conversation, making the conversation unavailable to the 
program. 


DEALLOCATE_ NORMAL indicates that the remote 
transaction program issued a DEALLOCATE verb 
specifying the TYPE(SYNC_LEVEL) or TYPE(FLUSH) 
parameter. APPC/PC reports this return code to the local 
transaction program on a verb the program issues in 
receive state. After APPC/PC issues this return code, it 
deallocates the conversation, making the conversation 
unavailable to the program. 


INCOMPLETE indicates that the verb has not finished 
and must be re-issued unchanged before any other verb 
with the same TP_ID. Before re-issuing the verb, you 


should try to issue verbs on other transaction programs, 
including other unfinished verbs. If you are queueing 
incoming ALLOCATEs in the LUs, you should also 
periodically issue GET ALLOCATE. This return code is 
returned only if ATTACH PU 
(RETURN_CONTROL=INCOMPLETE) was issued. For 
more information on this return code, see “System 
Deadlocks” on page 10-2. 


INCOMPLETE ALTERED _ VERB indicates that a verb 
was issued with the same TP_ID as that of an unfinished 
verb, or the unfinished verb was altered before it was 
re-issued. 


Note: You may change the first 12 bytes of an incomplete 
verb so you can place list pointers in this area to create a 
list of incomplete verbs. 


INVALID_VERB indicates that APPC/PC did not 
recognize the issued verb. APPC/PC reports this return 
code on the verb issued. The state of the conversation 
remains unchanged. 


OK indicates that the verb issued by the local transaction 
program executed successfully. That is, APPC/PC 
performed the function defined for the verb, to the point 
where APPC/PC returns control to the transaction 
program. The state of the basic conversation is as defined 
for the verb. 


POSTING_NOT_ACTIVE indicates that a transaction 
program issued a WAIT verb for which none of the listed 
conversations had an active POST _ON_ RECEIPT 
outstanding. APPC/PC reports this return code on the 
WAIT verb. 


PROG_ERROR_NO_TRUNC indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(PROG) parameter, the conversation for the 
remote transaction program was in send state, and the 
SEND_ERROR did not truncate a logical record. 
APPC/PC does not truncate a record if the remote 
transaction program issues SEND_ERROR before sending 
logical records or after sending a complete logical record. 


7-12 


APPC/PC reports this return code to the local transaction 
program on a RECEIVE_AND_WAIT or 

RECEIVE _IMMEDIATE verb which the local transaction 
program issues before receiving any logical records or 
after receiving one or more complete logical records. The 
conversation remains in receive state. 


PROG_ERROR_ PURGING indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(PROG) parameter, and the conversation for the 
remote transaction program was in receive or confirm 
state. The SEND ERROR may cause data sent by the 
local transaction program to be purged. 


Purging occurs when a transaction program issues 
SEND_ERROR in receive state before it receives all the 
information sent by its partner transaction program (that 
is, the information sent before APPC/PC reports the 
error). The purging can occur at the local LU, remote 
LU, or both. No purging occurs when a program issues 
SEND_ERROR in confirm state or receive state after 
receiving all the information sent by its partner 
transaction program. 


APPC/PC normally reports this return code to the local 
transaction program on a verb the local transaction 
program issues after sending information to the remote 
program. However, APPC/PC can report this return code 
on a verb the transaction program issues before sending 
any information, depending on the verb and when the 
program issues it. APPC/PC leaves the conversation in 
receive state. 


PROG_ERROR_TRUNC indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(PROG) parameter, the conversation for the 
remote transaction program was in send state, and the 
SEND_ERROR truncated a logical record. Truncation 
occurs when a transaction program begins sending a 
logical record and then issues SEND_ ERROR before 
sending the complete logical record. 


APPC/PC reports this return code to the local program on 
a RECEIVE. AND WAIT or RECEIVE_IMMEDIATE 


7-13 


verb the program issues after receiving the truncated 
logical record. APPC/PC leaves the conversation in 
receive state. 


SVC_ERROR NO_TRUNC indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(SVC) parameter, the conversation for the 
remote transaction program was in send state, and the 
SEND_ERROR did not truncate a logical record. No 
truncation occurs when a transaction program issues 
SEND_ERROR before sending logical records or after 
sending a complete logical record. 


APPC/PC reports this return code to the local transaction 
program on a RECEIVE_AND_WAIT or 
RECEIVE_IMMEDIATE verb the program issues before 
receiving any logical records or after receiving one or 
more complete logical records. APPC/PC places the 
conversation in receive state. 


SVC_ERROR_ PURGING indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(SVC) parameter, and that the conversation for 
the remote transaction program was in receive or confirm 
state. The SEND_ERROR may cause information to be 
purged. 


Purging occurs when a transaction program issues 
SEND_ERROR in receive state before it receives all the 
information sent by its partner transaction program (that 
is, the information sent before APPC/PC reports the 
SVC_ERROR_ PURGING return code to the partner 
program). The purging can occur at the local LU, remote 
LU, or both. No purging occurs when a transaction 
program issues SEND_ERROR in confirm or receive 
state after receiving all the information sent by its 
partner transaction program. 


APPC/PC normally reports this return code to the local 
transaction program on a verb the program issues after 
sending information to the remote transaction program. 
However, APPC/PC can report the return code on a verb 
that the transaction program issues before it sends any 
information, depending on the verb and when the 
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transaction program issues it. APPC/PC leaves the 
conversation 1n receive state. 


SVC_ERROR_ TRUNC indicates that the remote 
transaction program issued a SEND_ERROR specifying 
the TYPE(SVC) parameter, the conversation for the 
remote transaction program was in send state, and the 
SEND_ERROR truncated a logical record. Truncation 
occurs when a transaction program begins sending a 
logical record and then issues SEND_ERROR before 
sending the complete logical record. 


APPC/PC reports this return code to the local transaction 
program on a RECEIVE _AND_ WAIT or 
RECEIVE_IMMEDIATE verb that the program issues 
after receiving the truncated logical record. APPC/PC 
leaves the conversation in receive state. 


Note: 


The PARAMETER _CHECK and STATE_CHECK errors 
can also occur on any verb. When APPC/PC detects these 
error conditions, it does not try to execute the verb. A 
PARAMETER _ CHECK error occurs when APPC/PC 
detects an invalid parameter value. A STATE CHECK 
error occurs when the conversation is not in the correct 
state for the verb the transaction program is issuing. The 
verb descriptions list the secondary return codes which 
identify the causes of these errors. 


The following table correlates the verbs to the return 
codes on which they can be returned. 
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Return Codes 


ALLOCATION ERROR 
CONV_FAILURE NO RETRY 
CONV FAILURE RETRY 
CONVERSATION TYPE MIXED 
DATA POSTING BLOCKED 
DEALLOCATE ABEND PROG 
DEALLOCATE ABEND SVC 
DEALLOCATE ABEND TIMER 
DEALLOCATE NORMAL 
INCOMPLETE 

INCOMPLETE _ALTERED VERB 
OK 

PARAMETER CHECK 
POSTING NOT ACTIVE 

PROG ERROR_NO TRUNC 
PROG ERROR PURGING 
PROG ERROR _TRUNC 

STATE CHECK 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_ PURGING 

SVC ERROR_TRUNC 
UNSUCCESSFUL 


MOOK KO OS 
KKM MM KK KO 
Mm OO OO OK 

aehehaeheahakeleltelalalalalalale: 
M6 6 OS OE OK OE OK OOO OO 
MMMM KKK OO OS 
OS OS OS OS OS OS OS 


mS 6 OS OS OK 


Pe De OO OK OS OK OS 


Each X in the table means that APPC/PC can return the 
indicated return code with the corresponding verb. 


The individual verb descriptions list the applicable return 
codes. The descriptions for most verbs do not explicitly 
list the secondary return code of the 
ALLOCATION_ERROR return code because they can 
occur at any time and are not necessarily a result of the 
verb on which they are returned. The description of the 
ALLOCATE verb, however, lists the two secondary codes 
that indicate an allocation failure. 
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Verb Descriptions 


Detailed descriptions of the basic conversation verbs are 
as follows: 


ALLOCATE 


Allocates a session, if one is available, between the local 
LU and a remote LU, and establishes a basic or mapped 
conversation between the local transaction program and a 
remote transaction program on that session. APPC/PC 
assigns a CONV_ID to the conversation. Except for the 
first conversation of a remotely initiated transaction 
program, the transaction program must issue this verb 
before it can issue any verbs that refer to the 
conversation. 


A program can request the allocation of a mapped 
conversation and then issue basic conversation verbs on a 
mapped conversation. However, the local transaction 
program is then responsible for providing its own mapping 
layer. 


For example, you want to provide your mapping layer in 
order to do data mapping, or to permit 
MC_POST_ON_RECEIPT and MC_WAIT, neither of 
which are implemented by the APPC/PC mapped 
conversation API. 
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Supplied Parameters: 
ALLOCATE | TP_ID (variable) 

PARTNER _LU NAME (variable) 

MODE_NAME (variable) 


TPN (variable) 


CONVERSATION_TYPE (BASIC_CONVERSATION) 
(MAPPED CONVERSATION) 


RETURN_CONTROL (WHEN_SESSION_ALLOCATED) 
(IMMEDIATE ) 
(WHEN _SESSION_FREE) 


SYNC_LEVEL (NONE) 
(CONFIRM) 


SECURITY (NONE) 
(SAME) 
(PGM (USER_ID (variable) 
PASSWORD (variable) ) 
PIP DATA LENGTH (variable) 


PIP_DATA (variable) 
Returned Parameters: 


CONV_ID (variable) 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP_ STARTED” on 
page 5-58. 


PARTNER _LU_NAME specifies the name (in EBCDIC) 
of the remote LU at which the remote transaction 
program is located. The local LU uses the 
PARTNER_LU_NAME to identify the remote LU when 
allocating a session. That is, the PARTNER LU NAME 
is the remote LU network name. 
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MODE_NAME specifies the mode name (in EBCDIC) 
designating the network properties for the session 
APPC/PC is to allocate for the conversation. For 
example, one network property is the class of service 
APPC/PC provides for the session used. Basic 
conversations cannot use the SNASVCMG mode. 


TPN specifies the name (in EBCDIC) of the remote 
transaction program that manages the other end of the 
conversation. 


CONVERSATION_TYPE specifies the type of 
conversation APPC/PC is to allocate. 


BASIC_CONVERSATION directs APPC/PC to 


allocate a basic conversation. 


MAPPED_CONVERSATION directs APPC/PC to 


allocate a mapped conversation. 


RETURN_CONTROL specifies when the local LU is to 
return control to the local transaction program after the 
program requests the LU to allocate a session for the 
conversation. APPC/PC reports allocation errors caused 
by the local LU failing to obtain a session for the 
conversation on this verb. APPC/PC also reports 
allocation errors caused by the remote LU rejecting the 
conversation request on a subsequent verb. The valid 
values for the RETURN_CONTROL parameter are: 


WHEN_SESSION_ALLOCATED directs the LU to 
allocate a session for the conversation before 
returning control to the transaction program. Except 
for instances of conversation failure, the LU does not 
return control to the transaction program until a 
session becomes available. 


This option may cause a deadlock situation if there are 
not enough sessions for the currently active 
conversations of all transaction programs. Specifying 
the RETURN_CONTROL(IINCOMPLETE) option on 
the ATTACH _PU verb can confine the problem to the 
currently executing transaction program, but if this 
program has itself used up all sessions, the program 
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can still cause a deadlock situation by using the 
WHEN_SESSION ALLOCATED option. You must 
analyze your operating environment to determine if 
this option is safe. For more information on this 
problem, see “System Deadlocks” on page 10-2. 


e IMMEDIATE directs the LU to allocate a session for 
the conversation if a contention-winner session is 
immediately available. This option returns control to 
the transaction program immediately with a return 
code indicating whether a session is allocated. In this 
case, the local LU does not have to wait for a response 
from the partner LU, and the ALLOCATE verb does 
not require information to be sent to the partner LU. 


— Areturn code of OK indicates that a session is 
immediately available and is allocated for the 
conversation. A session is immediately available 
when it is active, it is not allocated to another 
conversation, and the local LU is the contention 
winner for the session. 


— A return code of UNSUCCESSFUL indicates that a 
session is not immediately available and that the 
LU did not perform the allocation. 


e WHEN_SESSION_FREE directs the LU to allocate 
a session for the conversation only if a session (either 
a contention winner or loser) is available or able to be 
activated, and then to return control to the 
transaction program with a return code indicating 
whether a session is allocated. 


— A return code of OK indicates that a session is 
available and is allocated for the conversation. If 
activation of a session is necessary, the LU 
performs the session activation before returning 
control to the transaction program. 


— A return code of ALLOCATION_ERROR indicates 
that a session is unavailable and that the LU 
cannot activate a new session. No session is 
allocated. 
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SYNC_LEVEL specifies the synchronization level that 
the local and remote programs can use for this 
conversation. 


NONE specifies that the transaction programs do not 
perform confirmation processing on this conversation. 
The programs do not issue any verbs and do not 
recognize returned parameters relating to the 
synchronization function. 


CONFIRM specifies that the transaction programs can 
perform confirmation processing on this conversation. 
The programs can issue verbs and recognize returned 
parameters relating to confirmation. 


SECURITY specifies access security information that the 
remote LU uses to validate access to the remote 
transaction program and its resources. The access 
security information includes a user ID and a password 
provided using the following arguments: 


NONE specifies that this conversation does not use 
conversation level security. 


SAME directs the remote LU to use the user ID it has 
already verified as part of the allocation request that 
initiated execution of the local program. This option 
also causes APPC/PC to send this saved user ID to the 
remote LU with an ‘already verified’ indication. If 
there was no user ID, APPC/PC sends the allocation 
request with no security information and a ‘not 
already verified’ indication. 


PGM directs the remote LU to use the security 
information that the local transaction program 
provides on this parameter. The local transaction 
program uses the following arguments to provide this 
security information: 


— USER_ID specifies the ID (in EBCDIC) of the end 
user. The USER_ID value is 8 bytes long. The 
remote LU uses this value and the password to 
verify the identity of the end user making the 
allocation request. In addition, the remote LU may 
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use the USER_ID for auditing or accounting to 
associate conversation accesses with the end user. 


— PASSWORD specifies the password (in EBCDIC) 
of the end user. The PASSWORD value can be up 
to 8 bytes long. The remote LU uses this value and 
the USER_ID to verify the identity of the end user 
making the allocation request. 


PIP_DATA_ LENGTH specifies the length of the 
program initialization parameters for the remote program. 
Set this parameter to 0 if there is no PIP data. 


PIP_DATA specifies the variable that contains the PIP 
data that the local program is sending to the remote 
program. The transaction program must format the PIP 
data according to the GDS format specified in “FM 
Headers” in the SNA Reference Summary. 


Returned Parameters: 
CONV _ID indicates the ID of the new conversation. 


RETURN_CODE indicates the result of verb execution. 
The ALLOCATE return codes are: 


e PARAMETER _CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


- DATA AREA ACROSS SEGMENT: APPC/PC 
does not permit PIP data to cross a segment 
boundary. 


—- BAD_TPN_LEN: The value that TPN specifies is 
too short (less than 1) or too long (greater than 64). 


- BAD CONV_TYPE: APPC/PC does not recognize 
the specified CONVERSATION_ TYPE. 


— BAD _SYNC_LEVEL: APPC/PC does not 
recognize the specified SYNC_LEVEL. 
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— BAD SECURITY _ SELEC: -APPC/PC does not 
recognize the specified SECURITY. 


— BAD _RETURN_CONTROL: APPC/PC does not 
recognize the specified RETURN_CONTROL. 


— TOO_BIG_SEC_TOKENS: APPC/PC does not 
accept a password or user ID longer than 8 bytes. 


— PIP_LEN_INCORRECT: APPC/PC does not 
accept PIP data longer than 32767 bytes. 


— NO_USE_OF SNASVCMG: APPC/PC does not 
accept SNASVCMG as the value for the 
MODE_NAME parameter. 


— UNKNOWN_PARTNER MODE: APPC/PC does 
not recognize the specified PARTNER _LU_NAME 
or MODE_ NAME. 


e ALLOCATION ERROR: The following two secondary 
return codes indicate the local transaction programs 
failure to obtain a conversation. For detailed 
information on these secondary return codes, see 
“Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


— ALLOCATION FAILURE_NO_RETRY: 
APPC/PC cannot allocate the conversation because 
of a permanent error condition. 


— ALLOCATION FAILURE RETRY: APPC/PC 
cannot allocate the conversation because of 
temporary error condition. 


e UNSUCCESSFUL: The program specified 
RETURN_CONTROLUMMEDIATE) and APPC/PC 
could not allocate the conversation because no 
contention-winner sessions were available. 


For detailed information on the following return codes, 


see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 
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APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 

INCOMPLETE 

INCOMPLETE _ALTERED_ VERB 
OK. 


State Changes: 


The conversation enters send state if the 


RETURN_CODE indicates OK. 


Notes: 


1. 


The local LU does not send PIP data immediately 
unless the local transaction program issues a verb 
(other than SEND_ DATA) that explicitly directs the 
LU to flush its send buffer. Otherwise, the LU retains 
the PIP parameter of the ALLOCATE verb and 
accumulates data from subsequent SEND _DATA 
verbs. 


The LU sends this data to the partner LU when it 
accumulates enough data for transmission. The 
amount of information that is sufficient for 
transmission depends on the characteristics of the 
session allocated for the conversation, and can vary 
from session to session. 


The local transaction program can ensure that 
APPC/PC connects the remote transaction program as 
soon as possible by issuing the FLUSH verb 
immediately after the ALLOCATE verb. 


Contention for a session can occur when two LUs 
connected by a session both try to allocate a 
conversation on the session at the same time. 
APPC/PC resolves the contention by making one LU 
the contention winner of the session and the other LU 
the contention loser of the session. 


The contention-winner LU allocates a conversation on 
a session without asking permission from the 
contention-loser LU. Conversely, the contention-loser 
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LU requests permission from the contention-winner LU 
to allocate a conversation on the session. Then the 
contention-winner LU either grants or rejects the 
request. 


The remote transaction program starts the 
conversation in receive state. 


For an IBM Token-Ring Network, one link must be 
reserved for outgoing calls to enable the ALLOCATE 
verb to complete. For more information on reserving 
links, see “Entering Information for an IBM 
Token-Ring DLC” in the APPC/PC Installation and 
Configuration Guide 


You must specify the PARTNER _LU_NAME, 
MODE_NAME, TPN, USER_ID, and PASSWORD in 
EBCDIC. You can use the CONVERT verb to convert 
these parameter values from ASCII to EBCDIC. 
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CONFIRM 


Sends a confirmation request to a remote transaction 
program and waits for a reply. This verb enables the local 
and remote programs to synchronize their processing with 
one another. CONFIRM also causes the LU to flush its 
send buffer. To use this verb, the program must have 
allocated the conversation with a synchronization level of 
CONFIRM. 


Supplied Parameters: 


CONFIRM TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
_ see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the transaction program is sending a confirmation 
request. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The CONFIRM return codes are as follows: 


e OK: The remote transaction program replied 
CONFIRMED. 


e PARAMETER CHECK 
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— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— CONFIRM_ON SYNC_NONE: APPC/PC does 
not permit the transaction program to use this verb 
if it allocated the conversation with 
SYNC_LEVEL(NONE). 


e STATE_CHECK 


— CONFIRM BAD STATE: The conversation is not 
in send state. 


— CONFIRM NOT _LL_BDY: The conversation is 
in send state, and the transaction program started, 
but did not finish, sending a logical record. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
INCOMPLETE 

INCOMPLETE _ALTERED_ VERB 
PROG_ERROR_PURGING 
SVC_ERROR_PURGING. 


REQUEST_TO SEND_ RECEIVED indicates whether 
the local LU received a REQUEST _TO_SEND verb. The 
two indications APPC/PC can return are YES and NO. 
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YES indicates that the local LU received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote program issued a 
REQUEST_TO_SEND verb to request the local 
program to enter receive state and place the remote 
program in send state. 


NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification from the remote 


program. 


State Changes: 


The state of the conversation does not change when the 
RETURN_CODE indicates OK. For information on state 
changes when the RETURN_CODE indicates a code other 
than OK, see “Understanding Basic Conversation Return 
Codes” on page 7-5. 


Notes: 


1. 


The transaction program can use this verb for various 
application-level functions. For example: 


e The transaction program can issue this verb 
immediately following an ALLOCATE to determine 
whether the allocation of the conversation is 
successful before sending data. 


e The transaction program can issue this verb to 
request acknowledgment of data it sent to the 
remote transaction program. The remote program 
can respond by issuing CONFIRMED to indicate 
that it received and processed the data without 
error, or by issuing SEND ERROR to indicate that 
it found an error. 


When the REQUEST_TO_ SEND_RECEIVED 
parameter indicates YES, the remote transaction 
program is requesting that the local transaction 
program enter receive state and place the remote 
transaction program in send state. A transaction 
program enters receive state by issuing the 


PREPARE _TO_RECEIVE verb or the 
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RECEIVE_AND_WAIT verb. The partner transaction 
program enters send state after it issues the 
RECEIVE_AND_ WAIT verb or the 

RECEIVE. IMMEDIATE verb, and receives the SEND 
indication from its partner transaction program on the 
WHAT_RECEIVED parameter. 
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CONFIRMED 


Sends a confirmation reply to the remote transaction 
program. This verb enables the local and remote 
programs to synchronize their processing. The local 
program can issue this verb when it receives a 
confirmation request. (For more information on 
confirmation requests, see the WHAT. RECEIVED 
parameter of the RECEIVE _AND_ WAIT or the 
RECEIVE_IMMEDIATE verbs). 


Supplied Parameters: 
TP_ID (variable) 


CONFIRMED 


CONV_ID (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the transaction program is sending a confirmation reply. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The CONFIRMED return codes are as follows: 


e PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 
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— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


e STATE_CHECK 


— CONFIRMED BAD STATE: The conversation is 
not in confirm state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


The conversation enters receive state if the transaction 
program received CONFIRM on the preceding 
RECEIVE _AND_ WAIT or RECEIVE. IMMEDIATE verb. 


The conversation enters send state if the transaction 
program received CONFIRM_SEND on the preceding 
RECEIVE_AND_WAIT or RECEIVE_IMMEDIATE verb. 


The conversation enters reset state if the transaction 
program received CONFIRM _DEALLOCATE on the 
preceding RECEIVE_AND_ WAIT or 

RECEIVE_ IMMEDIATE verb. 

Note: 


The transaction program can issue this verb only as a 
reply to a confirmation request. 


CONFIRMED 7-31 


DEALLOCATE 


Deallocates the specified conversation. DEALLOCATE 
can perform the function of the FLUSH or the CONFIRM 
verb before it deallocates the conversation. APPC/PC 
discards the CONV_ID after APPC/PC deallocates the 
associated conversation. 


Supplied Parameters: 
DEALLOCATE TP_ID (variable) 


CONV_ID (variable) 


TYPE (SYNC_LEVEL) 
(FLUSH) 
(ABEND PROG) 
(ABEND_SVC) 
(ABEND_TIMER) 


LOG _DATA_ LENGTH (variable) 


LOG_DATA (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation that the 
transaction program is deallocating. 


TYPE specifies the type of deallocation APPC/PC is to 
perform. 


e SYNC_LEVEL directs APPC/PC to deallocate the 
conversation based on one of the following 
synchronization levels allocated to this conversation: 
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— Ifthe SYNC_LEVEL is NONE, APPC/PC performs 
the function of the FLUSH verb and then 
deallocates the conversation normally. 


— If the SYNC_LEVEL is CONFIRM, APPC/PC 
performs the function of the CONFIRM verb and, if 
it is successful (as indicated by a return code of OK 
on this DEALLOCATE verb), APPC/PC deallocates 
the conversation normally. If it is unsuccessful, 
the return code determines the state of the 
conversation. 


e FLUSH directs APPC/PC to perform the function of 
the FLUSH verb, and then to deallocate the 
conversation normally. 


e ABEND_PROG, ABEND_SVC, or ABEND_TIMER 
directs APPC/PC to perform the function of the 
FLUSH verb when the conversation is in send state, 
and then to deallocate the conversation abnormally. 
APPC/PC can perform logical record truncation if the 
program deallocates a conversation in send state. If 
the program deallocates a conversation in receive 
state, APPC/PC can perform data purging. 


For types SYNC_LEVEL and FLUSH, APPC/PC informs 
the remote transaction program of the deallocation with a 
DEALLOCATE NORMAL return code. For type 
ABEND_PROG, ABEND_SVC, or ABEND_ TIMER, 
APPC/PC informs the remote transaction program of the 
deallocation with a DEALLOCATE_ABEND_ PROG, 
DEALLOCATE_ABEND_ SVC, or 

DEALLOCATE _ABEND_ TIMER return code 
(respectively), except in the following case: if the remote 
transaction program has issued a SEND_ERROR, it may 
receive a DEALLOCATE_NORMAL return code instead 
of one of the DEALLOCATE ABEND return codes. 


If APPC/PC performs the FLUSH or the CONFIRM 


function as part of the DEALLOCATE verb, APPC/PC 
also flushes the send buffer of the local LU. 
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LOG_DATA_LENGTH specifies the number of bytes of 
log data to be sent. Set this parameter to 0 if there is no 
log data. The parameter must be 0 for any TYPE value 
except ABEND PROG, ABEND_SVC or 
ABEND_TIMER. Values between 0 and 65535 are valid 
for this parameter, but the sum of this value and the offset 
of the LOG_DATA address must not exceed 65535. This 
limit prevents the log data from crossing a segment 
boundary. 


LOG_DATA specifies the variable (consisting of a single 
LL) containing transaction program error information 
that APPC/PC is to send to the partner LU. The partner 
LU either discards the data or saves it in a system error 
log. (For a description of how APPC/PC passes the 
LOG_DATA it receives to the application subsystem, see 
“Managing Logged Errors (SYSLOG Exit)” on page 2-10.) 
The transaction program must format this error 
information as an error log GDS variable (for the correct 
format, see “GDS Variables” in the SNA Reference 
Summary). 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The TYPE parameter determines which of the following 
DEALLOCATE return codes APPC/PC can return to the 
program. 


e PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


- DATA _ AREA ACROSS _SEGMENT: The log 
data area crosses a segment boundary. 


- DEALLOCATE BAD TYPE: APPC/PC does not 
recognize the specified TYPE. 
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— LOG_LL_WRONG: The program specified an 


incorrect length for the log data. 


e STATE _CHECK 


~ DEALLOC_FLUSH_BAD_ STATE: The program 
specified the TYPE(SYNC_LEVEL) parameter for 


a conversation specified with 


SYNC_LEVEL(NONE) and the conversation is not 
in send state. Alternatively, the program may have 


specified TYPE(FLUSH) when the conversation 


was not in send state. 


— DEALLOC_CONFIRM_BAD_ STATE: The 


program specified TYPE(SYNC_LEVEL) for a 


conversation specified with 


SYNC_LEVEL(CONFIRM) when the conversation 


was not in send state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 


page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK. 


If the program specifies TYPE(SYNC_LEVEL) and the 


synchronization level allocated to this conversation is 
CONFIRM, APPC/PC can report one of the following 
return codes: (For detailed information on these return 
codes, see “Understanding Basic Conversation Return 


Codes” on page 7-5 and Appendix C, “Verb Return 
Codes.”) 


ALLOCATION_ERROR 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 


DEALLOCATE 
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e DEALLOCATE_ABEND_TIMER 
e PROG_ERROR_PURGING 
e SVC_ERROR_PURGING. 


State Changes: 


The conversation enters reset state when the 
RETURN_CODE indicates OK. For information on state 
changes when the RETURN_CODE indicates other than 
OK, see “Understanding Basic Conversation Return 
Codes” on page 7-5. 


Notes: 


1. A transaction program can use the 
TYPE(SYNC_LEVEL) parameter to deallocate the 
conversation based on the synchronization level 
allocated to the conversation. 


e If the synchronization level is NONE, APPC/PC 
deallocates the conversation unconditionally. 


e If the synchronization level is CONFIRM, 
APPC/PC deallocates the conversation if the 
remote transaction program issues CONFIRMED to 
respond to the confirmation request. The 
conversation remains allocated if the remote 
transaction program issues SEND_ERROR to 
respond to the confirmation request. 


2. A transaction program can use the TYPE(FLUSH) 
parameter to deallocate the conversation 
unconditionally, regardless of its synchronization 
level. 


3. A transaction program can use the 
TYPE(ABEND_PROG), TYPE(ABEND_ SVC), and 
TYPE(ABEND_ TIMER) parameters to deallocate the 
conversation unconditionally, regardless of its 
synchronization level and its current state. 
Specifically: 


e The TYPE(ABEND_ PROG) parameter is for use by 
a transaction program when it detects an error 
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condition that prevents further useful 
communication; that is, communications that would 
lead to successful completion of the transaction. 
The specific use and meaning of ABEND _ PROG 
are program-defined. 


e The TYPE(ABEND_SVC) parameter is for use by 
an LU services component, such as one that 
processes mapped conversation verbs, when it 
detects an error condition caused by its peer LU 
services component in the remote LU. For 
example, the LU services component issues the 
DEALLOCATE verb with this parameter when it 
detects a format error in control information sent 
by the peer LU services component. 


e The TYPE(ABEND_TIMER) parameter is for use 
by an LU services component, such as one that 
processes mapped conversation verbs, when it 
detects or is informed of a condition that requires 
the conversation to be deallocated without further 
communication. For example, the LU services 
component issues the DEALLOCATE verb with this 
parameter if too much time elapses without 
receiving any information, or an operator 
prematurely ends program execution. 


4, DEALLOCATE with TYPE(ABEND_PROG), 
TYPE(ABEND_ SVC), or TYPE(ABEND_TIMER) 
resets or cancels posting. If posting is active and 
APPC/PC has posted the conversation, it resets the 
posting. If posting is active and APPC/PC has not 
posted the conversation, APPC/PC cancels posting so 
that no more posting occurs. For more details about 
posting, see the description of the 
POST_ON_RECEIPT verb. 
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FLUSH 


Flushes the send buffer of the local LU by sending all 
buffered information to the remote LU. Information 
buffered by the LU can come from ALLOCATE, 
DEALLOCATE, SEND_DATA, 
PREPARE_TO_RECEIVE, and SEND_ERROR. Refer to 
the descriptions of these verbs for more details on this 
buffered information, including when APPC/PC places 
information in the buffer. 


Supplied Parameters: 
TP_ID (variable) 


CONV_ID (variable) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation for which 
the local LU is to flush its send buffer. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The FLUSH return codes are as follows: 


e PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 
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— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


STATE CHECK 


—~ FLUSH NOT SEND STATE: The conversation 
is not in send state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_ MIXED 
OK. 


State Changes: 


None 


Notes: 


iL 


A transaction program can use this verb to optimize 
the processing between the local and remote 
transaction programs. The LU normally buffers the 
data from consecutive SEND DATA verbs until it has 
a sufficient amount for transmission. At that time it 
transmits the buffered data. However, the local 
transaction program can issue FLUSH in order to 
force the LU to send the buffered data, minimizing the 
delay in the remote transaction programs processing of 
the data. 


The LU flushes its send buffer only when it has 


information to transmit; otherwise, the FLUSH verb 
has no effect. 
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GET_ATTRIBUTES 


Returns the attributes of the specified conversation. 


Supplied Parameters: 
GET_ATTRIBUTES TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 
LU_ID (variable) 
OWN_NET_NAME (variable) 
OWN_LU_NAME (variable) 
PARTNER_LU_NAME (variable) 


PARTNER_FULLY_QUALIFIED_LU_NAME 
(variable) 


MODE_NAME (variable) 


SYNC_LEVEL (variable) 


USER_ID (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation for which 
the attributes are desired. 
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Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The GET_ATTRIBUTES return codes are: 


e PARAMETER CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_ DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


LU_ID indicates the identifier of the LU at which the 
local transaction program is located. APPC/PC passes 
this value to the application subsystem when the 
application subsystem defines the LU by issuing the 
ATTACH _LU verb. (For more information on the LU_ID 
parameter, see “ATTACH LU” on page 5-7.) 


OWN_NET_NAME indicates the name (in EBCDIC) of 
the network containing the LU at which the local 
transaction program is located. 


OWN_LU_NAME indicates the name (in EBCDIC) of 
the LU at which the local transaction program is located. 


PARTNER _LU_NAME indicates the name (in EBCDIC) 
of the LU at which the remote transaction program is 
located. The local LU uses this name to identify the 
remote LU when allocating a conversation. (For more 
information on the PARTNER _LU_NAME, see the 
description of the LU_NAME parameter of the 
ALLOCATE verb.) 
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PARTNER_FULLY_QUALIFIED_LU_NAME 
indicates the fully-qualified name (in EBCDIC) of the LU 
at which the remote transaction program is located. If 
APPC/PC does not know the partner’s fully-qualified LU 
name, it returns a null (0-length) value. 


MODE_NAME indicates the mode name (in EBCDIC) for 
the session on which APPC/PC allocated the 


conversation. 


SYNC_LEVEL indicates the level of synchronization 
processing specified for the conversation. For information 
on a conversation’s level of synchronization, see the 
description of the SYNC_LEVEL parameter of the 
ALLOCATE verb. The synchronization levels are: 


e NONE 
e CONFIRM. 


USER_ID indicates the user ID (in EBCDIC) if the 
program specified conversation-level security. An 
incoming ALLOCATE specifies this USER_ID when it 
requests the application subsystem to start a transaction 
program. If the program did not specify 
conversation-level security, or if the transaction program 
was initiated locally, APPC/PC returns a null (0-length) 
value for the USER_ID parameter. 


State Changes: 

None 

Note: 

The following parameters are returned in EBCDIC: 


OWN_NET_ID 

OWN_LU_NAME 

PARTNER_LU_NAME 
PARTNER_LU_FULLY_QUALIFIED_NAME 
MODE_NAME 

USER_ID. 
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You can use the CONVERT verb to convert these 
parameter values from ASCII to EBCDIC. 
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GET_TYPE 


Returns the conversation type (basic or mapped) of the 
specified conversation. A transaction program can issue 
this verb for both basic and mapped conversations. 
Supplied Parameters: 
GET_TYPE TP_ID (variable) 


CONV_ID (variable) 


Returned Parameters: 


RETURN_CODE (variable) 


TYPE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP__ peep. on 
page 5-58. 


CONV_ID specifies the ID of the conversation for which 
the conversation type is desired. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The GET_TYPE return codes are: 


e PARAMETER CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 
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For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


TYPE indicates the conversation type. The conversation 
types are: 


e BASIC. CONVERSATION indicates that a basic 
conversation was initiated by one of the following 
methods: 


— The conversation was initiated with an 
ALLOCATE(CONV_TYPE=BASIC __ 
CONVERSATION) verb. 


— An incoming ALLOCATE specified a basic 
conversation. 


e MAPPED CONVERSATION indicates that a mapped 
conversation was initiated by one of the following 
methods: 


— The conversation was initiated with an 


MC_ALLOCATE verb. 

— The conversation was initiated with an 
ALLOCATE(CONV_TYPE= MAPPED . 
CONVERSATION) verb. 


— An incoming ALLOCATE specified a mapped 
conversation. 


State Changes: 


None 
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Note: 


A program that APPC/PC can process at either the basic 
conversation API or the mapped conversation API uses 
this verb to determine which category of verbs, basic 
conversation or mapped conversation, to issue. 
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POST_ON_RECEIPT 


Causes the LU to post the specified conversation when 
information is available for the transaction program to 
receive. The information can be data, conversation 
status, or a request for confirmation. If the transaction 
program must wait for posting to occur, it should issue 
the WAIT verb after POST_ON_RECEIPT. 
Alternatively, the transaction program can determine 
whether posting has occurred by issuing the TEST verb 
after POST_ON_RECEIPT. 


Supplied Parameters: 
POST_ON_ RECEIPT TP_ID (variable) 
CONV_ID (variable) 


FILL (BUFFER) 
(LL) 


MAX LENGTH (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_ STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation the LU is 
to post when it receives information for the local 
transaction program. 


FILL specifies when the LU should post the conversation. 
e BUFFER directs the LU to post the conversation 
when the amount of available data is at least equal to 


that specified by the MAX_LENGTH parameter, or 
when the end of the data is available, whichever 
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occurs first. The amount of data required for posting 
is independent of the logical record format of the data. 


e LL directs the LU to post the conversation when it 
receives a complete or truncated logical record, or 
when it receives a part of a logical record that is at 
least equal in length to that specified by the 
MAX LENGTH parameter, whichever occurs first. 


The FILL(BUFFER) and FILL(LL) parameters for 
POST_ON_RECEIPT apply only at the time the 
transaction program issues the verb. They do not affect 
later uses of the POST _ON RECEIPT verb or the other 
verbs that use these parameters (RECEIVE_AND_ WAIT 
and RECEIVE IMMEDIATE). 


Posting also occurs independent of the FILL specification 
when the LU receives information other than data, such 
as conversation status (SEND, PROG_ERROR_TRUNC, 
or DEALLOCATE NORMAL indications, for example), or 
a confirmation request. 


MAX LENGTH specifies the maximum length of 
received data that causes posting to occur. The 
transaction program should set this value equal to the 
maximum amount of data that it is prepared to receive. 
The LU uses the MAX LENGTH and FILL parameters to 
determine when to post the conversation for the receipt of 
data. Values between 0 and 65535 bytes are valid for this 
parameter. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The POST _ON_ RECEIPT return codes are: 


e PARAMETER_CHECK 


— BAD _TP_ID: APPC/PC does not recognize the 
specified TP_ ID. 


—- BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 
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— INVALID LENGTH: The program specified an 
illegal value for the MAX LENGTH parameter. 


— P_ON_R_BAD FILL: The program specified an 
illegal value for the FILL parameter. 


STATE CHECK 
— P_ON_R_ NOT _RCV_STATE: The conversation 


is not in receive state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


None 


Notes: 


ds 


A transaction program can use this verb with the 
TEST and WAIT verbs. The program can use 
POST_ON_RECEIPT followed by WAIT to 
synchronize the receipt of data from multiple 
conversations. To prepare to receive data from 
multiple conversations, the program issues 
POST_ON_RECEIPT for each of the conversations 
and then issues WAIT for all of the conversations. 
The program then waits for the LU to post one of the 
conversations as soon as the LU receives the specified 
amount of data from its respective partner LUs. 


The transaction program can periodically use 
POST_ON_RECEIPT followed by TEST to continue 
processing until the test indicates that the local LU 
data is available. 
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2. Posting occurs when the LU has the specified amount 
of information that the transaction program can 
receive. This information can include conversation 
status, or a request for confirmation, as well as data 
from the partner transaction program. Fora 
description of the different types of information a 
program can receive, see the description of the 


RECEIVE _AND_ WAIT verb. 

3. Posting is active for a conversation after the 
transaction program issues POST_ON_ RECEIPT for 
the conversation and before it issues a verb that resets 
or cancels posting for that conversation. 

A transaction program can reset posting by issuing 
any of the following verbs after the LU posts the 
conversation: 


e DEALLOCATE with TYPE(ABEND_PROG), 
TYPE(ABEND_SVC), or TYPE(ABEND_TIMER) 


e RECEIVE _AND_WAIT 

e RECEIVE_IMMEDIATE 

e SEND_ERROR 

e TEST 

e WAIT. 

A transaction program can cancel posting by issuing 
any of the following verbs before the LU posts the 


conversation: 


e DEALLOCATE with TYPE(ABEND_PROG), 
TYPE(ABEND_SVC), or TYPE(ABEND_TIMER) 


e RECEIVE_IMMEDIATE 
e SEND_ERROR. 


The transaction program can reactivate posting by 
issuing another POST_ON_RECEIPT verb. 
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4. A transaction program can issue any number of 
POST_ON_RECEIPTs for a given conversation before 
it resets or cancels posting. The last 
POST_ON_RECEIPT that a program issues for a 
conversation determines when the LU posts the 
conversation. 


For example, a program can specify posting parameters 
by issuing POST_ON_ RECEIPT with FILL(BUFFER) 
and MAX _LENGTH(1000) in preparation to receive 
1000 bytes of data. If the program then issues the verb 
again with MAX LENGTH(500), the LU posts the 
conversation when 500 bytes of data are available. 
Alternatively, if the program issues 
POST_ON_RECEIPT again with FILL(LL), the LU 
posts the conversation in terms of logical records. 


5. POST_ON_RECEIPT with MAX LENGTH(0) or 
MAX LENGTH(1) directs the LU to post a 
conversation upon receipt of any number of bytes of 
data. 


6. The FILL(BUFFER) parameter directs the LU to post 
data according to the number of data bytes it receives, 
regardless of the logical record format. The LU posts 
the conversation when the number of data bytes in its 
receive buffer is equal to, or less than, the number 
specified with the MAX LENGTH parameter. The LU 
posts the conversation for less than the 
MAX _ LENGTH amount of data only when it receives 
the end of the data. The state of the conversation 
changes to send, confirm, or reset when the local LU 
receives the end of the data. 


For more information on the change in state, see the 
description of the RECEIVE _AND_WAIT verb. 


7. APPC/PC stores incoming data in its buffers during a 
POST operation. If the POST_ON_ RECEIPT verb 
specifies a large MAX LENGTH value, the received 
data could possibly exhaust the storage reserved for 
these buffers before the program accepted the data 
from the LU. If receive pacing is not specified, 
APPC/PC does not control the sending of data from 
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the partner transaction program and APPC/PC 
abnormally terminates if its workspace buffers become 
filled. If you use receive pacing and issue a WAIT or 
TEST for more than R(P-1) bytes of data (where P = 
pacing window, R = negotiated maximum RU size), 
APPC/PC may report a buffer full condition with a 
return code of DATA _POSTING_BLOCKED. When 
the buffers are full, you can choose to receive the data. 
If you want the buffers to accumulate more than this 
amount of data before you receive the data, 
reconfigure APPC/PC to increase the pacing window 
size or the MAX _RU_SIZE. Alternatively, you can 
choose not to use pacing. 
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PREPARE TO_RECEIVE 


Changes a basic conversation from send to receive state in 
preparation to receive data. Also performs the function of 
the FLUSH or CONFIRM verbs. 


Supplied Parameters: 
PREPARE_TO_ RECEIVE TP_ID (variable) 


CONV_ID (variable) 


TYPE (SYNC_LEVEL) 
(FLUSH) 


LOCKS (SHORT) 
(LONG) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 
the local transaction program is preparing to receive data. 


TYPE specifies the type of prepare-to-receive to be 
performed for this conversation. 


e SYNC_LEVEL directs APPC/PC to perform the 
prepare-to-receive based on the synchronization level 
allocated to this conversation: 


— If the SYNC_LEVEL is NONE, 
PREPARE TO_RECEIVE performs the function of 
the FLUSH verb and then places the conversation 
in receive state. 
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— Ifthe SYNC_LEVEL is CONFIRM, 
PREPARE TO RECEIVE performs the function of 
the CONFIRM verb (which includes the function of 
the FLUSH verb) and then, if the verb is 
successful, places the conversation in receive state. 
If the action of the CONFIRM verb is not 
successful (as indicated by a return code other than 
OK on the PREPARE _TO_ RECEIVE verb), the 
return code determines the state of the 
conversation. 


e FLUSH directs APPC/PC to perform the function of 
the FLUSH verb and then to place the conversation in 
receive state. 


LOCKS specifies when APPC/PC is to return control to 
the local transaction program after it performs the 
CONFIRM function of this verb. APPC/PC ignores this 
parameter unless TYPE(SYNC_LEVEL) is also specified 
and the synchronization level for this conversation is 


CONFIRM. 


e SHORT directs APPC/PC to return control as soon as 
the LU receives a CONFIRMED reply from the partner 
transaction program. The SHORT option returns 
control to the transaction program more quickly than 
the LONG option but it causes more information to be 
sent to the partner. 


e LONG directs APPC/PC to return control after the LU 
receives information, such as data, from the remote 
transaction program following a CONFIRMED reply. 
The LONG option causes less information to be sent to 
the partner than the SHORT option but it requires 
more time. 


Returned Parameters: 
RETURN_CODE indicates the result of verb execution. 
The TYPE parameter determines which of the following 


return codes can be returned to the program: 


e PARAMETER CHECK 
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~ BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— P_TO_R INVALID TYPE: APPC/PC does not 
recognize the specified TYPE. 


e STATE_CHECK 


— UNFINISHED LL: The conversation is in send 
state, and the program started, but did not finish, 
sending a logical record. 


— P_TO R NOT _SEND STATE: The conversation 
is not in send state. 


For detailed information on the following four return 
codes, see “Understanding Basic Conversation Return 
Codes” on page 7-5 and Appendix C, “Verb Return 
Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
INCOMPLETE . 
INCOMPLETE_ALTERED_ VERB 
OK. 


If the program specifies TYPE(SYNC_LEVEL) and the 
synchronization level allocated to this conversation is 
CONFIRM, APPC/PC can report one of the following 
return codes. For detailed information on these return 
codes, see “Understanding Basic Conversation Return 
Codes” on page 7-5 and Appendix C, “Verb Return 
Codes.” 


ALLOCATION_ERROR | 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 


PREPARE_TO_RECEIVE 7-55 


e DEALLOCATE_ABEND_TIMER 
e PROG_ERROR_PURGING 
e SVC_ERROR_PURGING. 


State Changes: 


The conversation enters receive state when the 
RETURN_CODE indicates OK. For information on state 
changes when the RETURN_CODE indicates other than 
OK, see “Understanding Basic Conversation Return 
Codes” on page 7-5. 


Notes: 


1. The conversation for the remote transaction program 
enters send state when the remote transaction program 
issues a RECEIVE. AND_ WAIT or 
RECEIVE _IMMEDIATE verb and receives the SEND 
indication from the local transaction program on the 
WHAT RECEIVED parameter. The remote 
transaction program can then send data to the local 
transaction program. 


2. If the local transaction program issues 
PREPARE _TO_RECEIVE with a SYNC_LEVEL of 
CONFIRM, the remote transaction program enters 
send state after issuing CONFIRMED. 
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RECEIVE _AND_WAIT 


Waits for information to arrive on the specified 
conversation and then receives the information. If 
information is already available, the transaction program 
receives it without waiting. The information can be data, 
conversation status, or a request for confirmation. 
APPC/PC returns control to the transaction program and 
indicates the type of information. 


The transaction program can issue this verb when the 
conversation is in either send or receive state. If the 
conversation is in send state, the LU flushes its send 
buffer, sending all buffered information and the SEND 
indication to the remote transaction program. The SEND 
indication places the conversation in receive state. The 
LU then waits for information to arrive from the remote 
transaction program. The remote transaction program 
sends data to the local transaction program after it 
receives the SEND indication. 


Supplied Parameters: 
RECEIVE_AND_WAIT TP_ID (variable) 
CONV_ID (variable) 


FILL (BUFFER) 
(TL) 


DATA_PTR (variable) 


MAX _LENGTH (variable). 
Returned Parameters: 


RETURN_CODE (variable) 
DATA_LENGTH (variable) 
DATA (see DATA PTR) 


WHAT RECEIVED (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 
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Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE _ TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 
the local transaction program is waiting to receive 
information. 


FILL specifies whether the transaction program should 
receive data according to the logical record format of the 
data or according to the number of bytes received. 


e BUFFER directs the LU to release the data in its 
receive buffer when the amount of available data is at 
least equal to that specified by the MAX LENGTH 
parameter, or when the end of data is available, 
whichever occurs first. The amount of data required 
for receipt by the transaction program is independent 
of its logical record format. The amount of data 
received is equal to, or less than, the number of data 
bytes specified on the MAX LENGTH parameter. The 
amount can be less than the specified length only at 
the end of the data. 


e LL directs the LU to release the data in its receive 
buffer when it receives a complete or truncated logical 
record, or a part of a logical record that is at least 
equal in length to that specified by the 
MAX_LENGTH parameter, whichever occurs first. 


The FILL(BUFFER) and FILL(LL) parameters for 
RECEIVE _AND_ WAIT apply only at the time the 
transaction program issues the verb. They do not affect 
later uses of the RECEIVE AND_ WAIT verb or the other 
verbs that use these parameters (POST_ON_RECEIPT 
and RECEIVE_ IMMEDIATE). 
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DATA_PTR specifies the address of the buffer which is 
to contain the received data. 


MAX LENGTH specifies the maximum amount of data 
(in bytes) that the transaction program is to receive. 
Values between 0 and 65535 are valid for this parameter, 
but the sum of this value and the offset portion of 
DATA_PTR must not exceed 65535. This limit keeps the 
incoming data from crossing a segment boundary. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The RECEIVE AND _ WAIT return codes are: 


e PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— DATA AREA ACROSS SEGMENT: The receive 
data area crosses a segment boundary. 


— RCV_AND_ WAIT _BAD FILL: The transaction 
program specified an illegal value for the FILL 
parameter. 


e STATE_CHECK 


—~ RCV_AND WAIT BAD STATE: The 
conversation is not in send or receive state. 


— RCV_AND_WAIT_NOT_LL_BDY: The 
conversation is in send state, and the program 
started, but did not finish, sending a logical record. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


e ALLOCATION_ERROR 
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APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_ SVC 
DEALLOCATE_ABEND_TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


DATA_LENGTH indicates the actual amount of data the 
transaction program received up to the maximum 

(MAX LENGTH). If the program receives information 
other than data the value of this variable is 0. 


DATA from the partner transaction program is received 
in the buffer specified by the address in the DATA_PTR 
parameter. APPC/PC does not place any information in 
this buffer when the program receives information other 
than data, as indicated by the WHAT_RECEIVED 
parameter. 


WHAT_RECEIVED indicates what the transaction 
program received. The program should examine this 
variable only when RETURN_CODE indicates OK. 
APPC/PC does not place any information in this variable 
when RETURN_CODE indicates other than OK. 


e DATA indicates that the transaction program received 
a MAX _ LENGTH amount of data or the end of data 
(independent of its logical record format) after 
specifying FILL(BUFFER). 
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e DATA COMPLETE indicates that the transaction 
program received a complete logical record or the last 
portion of a record after specifying FILL(LL). 


e DATA INCOMPLETE indicates that the transaction 
program received less than a complete logical record 
after specifying FILL(LL). The program can use 
another RECEIVE_AND_ WAIT (or possibly more 
than one) to receive the rest of the data for the 
incomplete logical record. 


e CONFIRM indicates that the remote transaction 
program has issued CONFIRM, requesting the local 
transaction program to respond by issuing 
CONFIRMED. The program can respond, instead, by 
issuing SEND_ERROR. 


e CONFIRM_DEALLOCATE indicates that the remote 
transaction program has issued DEALLOCATE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing CONFIRMED or SEND_ERROR. 


e CONFIRM_SEND indicates that the remote 
transaction program has issued 
PREPARE _TO_RECEIVE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing CONFIRMED, or by issuing 
another verb such as SEND_ ERROR. 


e SEND indicates that the remote transaction program 
has entered receive state, placing the local transaction 
program in send state. This indication signals that the 
local transaction program can issue the SEND_DATA 
verb to send data to the remote transaction program. 


REQUEST _TO_ SEND_ RECEIVED indicates whether 
the local LU has received a REQUEST _TO_ SEND 
notification. The indication is either YES or NO. 


e YES indicates that the local LU has received a 


REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
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has issued REQUEST_TO_SEND, requesting the local 
transaction program to enter receive state and place 
the remote transaction program in send state. 


NO indicates that the local LU has not received a 
REQUEST_TO_SEND notification from the remote 
transaction program. 


State Changes: 


A change in state occurs only if RETURN_CODE 
indicates OK. For information on state changes when 
RETURN_CODE indicates other than OK, see 
“Understanding Basic Conversation Return Codes” on 
page 7-5. 


The conversation enters receive state when the 
transaction program issues RECEIVE AND WAIT in 
send state and WHAT _ RECEIVED indicates DATA, 
DATA COMPLETE, or DATA_ INCOMPLETE. 


The conversation enters send state when 
WHAT RECEIVED indicates SEND. 


The conversation enters confirm state when 
WHAT RECEIVED indicates CONFIRM, 
CONFIRM_SEND, or CONFIRM _DEALLOCATE. 


No state change occurs when transaction program 
issues RECEIVE_AND_ WAIT in receive state and 
WHAT_RECEIVED indicates DATA, 
DATA_COMPLETE, or DATA_ INCOMPLETE. 


Notes: 


1. 


When the transaction program issues 
RECEIVE_AND_WAIT in send state, the LU 
implicitly executes a PREPARE TO RECEIVE with 
TYPE(FLUSH) before it executes the 

RECEIVE _AND_WAIT. See the description of the 
PREPARE TO_RECEIVE verb for details of its 
function. 
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2. When the transaction program specifies FILL(LL) to 
receive data in terms of logical records, the 
WHAT RECEIVED parameter can return either the 
DATA COMPLETE or the DATA. INCOMPLETE 
indication depending on the data received. The two 
sequences of events leading to these indications are: 


e The transaction program receives a complete 
logical record or the last portion of a record. The 
length of the record or portion of the record is 
equal to or less than the length specified on the 
MAX LENGTH parameter. The 
WHAT RECEIVED parameter indicates 
DATA COMPLETE. 


e The transaction program receives an incomplete 
logical record. The logical record is incomplete 
because: 


— The logical record contains more data than the 
program specified in the MAX LENGTH 
parameter, so the program receives a portion of 
the logical record equal to the specified length. 


— Only a portion of the logical record is available 
because the remote transaction program 
truncated it. The length of the truncated 
portion is less than, or equal to, the length the 
program specifies in the MAX LENGTH 
parameter. 


In these two cases, the WHAT RECEIVED 
parameter indicates DATA INCOMPLETE. The 
transaction program issues another 

RECEIVE _AND_ WAIT (or more than one) to 
receive the remainder of the logical record. 


For a definition of complete and incomplete logical 
records, see the description of the SEND_DATA verb. 


3. The transaction program specifies FILL(BUFFER) to 
receive data independent of its logical record format. 
This specification indicates that the program is to 
receive an amount of data less than, or equal to, the 
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length it specifies in the MAX LENGTH parameter. 
The local transaction program can receive less than 
the MAX LENGTH amount of data only at the end of 
the data sent from the remote transaction program. 
The end of data occurs when the conversation changes 
to send, confirm, or reset state after the program 
receives the data. When the transaction program 
specifies FILL(BUFFER), it must perform its own 
tracking of the data’s logical record format. 


4. A transaction program can use 
RECEIVE_AND_WAIT with MAX _LENGTH(0) to 
determine the type of information available without 
actually receiving any information. The 
RETURN_CODE and WHAT RECEIVED parameters 
indicate the type of information available as usual. If 
data is available and the program specified FILL(LL), 
the WHAT_RECEIVED parameter indicates 
DATA INCOMPLETE. If data is available and the 
program specified FILL(BUFFER), the 
WHAT _ RECEIVED parameter indicates DATA. In 
either case, however, the program receives no data. 


5. The transaction program receives only one kind of 
information at a time. For example, it may receive 
data or a CONFIRM request, but it cannot receive 
both at the same time. Also, if the remote transaction 
program truncates a logical record, the local 
transaction program receives an indication of the 
truncation from the RECEIVE_AND_ WAIT verb it 
issues after receiving the truncated record. 


The RETURN_CODE and WHAT_RECEIVED 
parameters indicate the kind of information the 
program receives. 


6. RECEIVE AND_ WAIT performs the same posting as 
the POST_ON_RECEIPT verb. If posting is already 
active when the local transaction program issues the 
RECEIVE_AND_WAIT verb, the parameter values of 
this verb supersede those specified with the previous 
POST_ON_RECEIPT verb. APPC/PC resets posting 
when it finishes executing RECEIVE_AND_WAIT. 
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For more information on posting, see the description of 
the POST_ON_ RECEIPT verb. 


The local transaction program usually receives a 
REQUEST_TO_SEND notification when it is in send 
state. APPC/PC reports the REQUEST_TO SEND 
notification to the program with a SEND_DATA verb 
or with a SEND_ERROR verb it issues in send state. 
However, the program can receive the 
REQUEST_TO_SEND notification when its 
conversation is in receive state under the following 
conditions: 


e When the local transaction program has just 
entered receive state and the remote transaction 
program issues REQUEST_TO_SEND before it 
enters send state. 


e When the remote transaction program has just 
entered receive state by issuing the 
PREPARE TO _RECEIVE verb (not 
RECEIVE AND_ WAIT), and then issues 
REQUEST _TO_SEND before the local transaction 
program responds by entering send state. This 
ambiguity can occur because 
REQUEST _TO_SEND is an expedited request and 
this expedited request can arrive ahead of the 
request carrying the SEND indication. 


The local transaction program might not be able to 
distinguish this condition from the preceding case. 
The remote transaction program can avoid this 
ambiguity by waiting until it receives information 
from the local transaction program before it issues 
the REQUEST_TO_SEND verb. 


e When the remote transaction program issues the 
REQUEST_TO_SEND in send state. 
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RECEIVE_IMMEDIATE 


Receives information that is available from the specified 
conversation, but does not wait for information to arrive. 
The information (if any) can be data, conversation status, 
or a request for confirmation. APPC/PC returns control 
to the transaction program with an indication of whether 
information was received and, if so, the type of 
information. 


Supplied Parameters: 
RECEIVE_IMMEDIATE TP_ID (variable) 


CONV_ID (variable) 


FILL (BUFFER) 
(LL) 


DATA_PTR (variable) 


MAX_LENGTH (variable) 


Returned Parameters: 


RETURN_CODE (variable) 
DATA_LENGTH (variable) 
DATA (see DATA_PTR) 
WHAT_RECEIVED (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 
the local transaction program is to receive information. 
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FILL specifies whether the program should receive data 
according to the logical record format of the data or 
according to the number of bytes received. 


e BUFFER directs the LU to release the data in its 
receive buffer when the amount of available data is at 
least equal to that specified by the MAX LENGTH 
parameter, or when the end of data is available, 
whichever occurs first. The amount of data required 
for receipt by the transaction program is independent 
of its logical record format. The amount of data 
received is equal to, or less than, the number of data 
bytes specified on the MAX LENGTH parameter. The 
amount can be less than the specified length only at 
the end of the data. 


e LL directs the LU to release the data from its receive 
buffer when it receives a complete or truncated logical 
record, or part of a logical record that is at least as 
long as the logical record specified by the 
MAX LENGTH parameter, whichever occurs first. 


The FILL(BUFFER) and FILL(LL) parameters for 
RECEIVE_IMMEDIATE apply only at the time the 
transaction program issues the verb. They do not affect 
later uses of the RECEIVE. IMMEDIATE verb or the 
other verbs that use these parameters 
(POST_ON_RECEIPT and RECEIVE_AND_ WAIT). 


DATA_PTR specifies the address of the buffer that is to 
contain the received data. 


MAX LENGTH specifies the maximum amount of data 
(in bytes) that the transaction program is to receive. 
Values between 0 and 65535 are valid for this parameter, 
but the sum of this value and the offset portion of 
DATA_PTR must not exceed 65535. This limit prevents 
the incoming data from crossing a segment boundary. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The RECEIVE _AND_WAIT return codes are: 
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PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


~ BAD CONV_ID: APPC/PC does not recognize the 
specified CONV_ ID. 


— DATA AREA ACROSS SEGMENT: The receive 


data area crosses a segment boundary. 


—- RCV_IMMD_BAD FILL: The program specified 
an illegal value for the FILL parameter. 


STATE_CHECK 


— RCV_IMMD NOT _RCV_STATE: The 
conversation is not in receive state. 


UNSUCCESSFUL: The local LU has nothing for the 
program to receive. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
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e SVC_ERROR_ PURGING 
e SVC_ERROR_TRUNC. 


DATA_LENGTH indicates the actual amount of data the 
local transaction program received up to the maximum 
(MAX LENGTH). If the program receives information 
other than data, or no information at all, the value of this 
variable is 0. 


DATA from the partner transaction program is received 
in the buffer specified by the address in the DATA PTR 
parameter. APPC/PC does not place any information in 
this buffer when the program receives information other 
than data, as indicated by the WHAT _RECEIVED 
parameter. 


WHAT_RECEIVED indicates what the transaction 
program received. The program should examine this 
variable only when RETURN_CODE indicates OK. 
APPC/PC does not place any information in this variable 
when RETURN_CODE indicates other than OK. 


e DATA indicates that the transaction program received 
a MAX LENGTH amount of data or the end of data 
(independent of its logical record format) after 
specifying FILL(BUFFER). 


e DATA COMPLETE indicates that the transaction 
program received a complete logical record or the last 
portion of a record after specifying FILL(LL). 


e DATA INCOMPLETE indicates that the transaction 
program received less than a complete logical record 
after specifying FILL(LL). The program can use one 
or more RECEIVE_IMMEDIATE or 
RECEIVE._AND_WAIT verbs to receive the rest of 
the data for the incomplete logical record. 


e CONFIRM indicates that the remote transaction 
program has issued CONFIRM, requesting the local 
transaction program to respond by issuing 
CONFIRMED. The program can respond, instead, by 
issuing SEND_ERROR. 
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e CONFIRM_SEND indicates that the remote 
transaction program has issued 
PREPARE TO RECEIVE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing CONFIRMED, or SEND_ERROR. 


e CONFIRM DEALLOCATE indicates that the remote 
transaction program has issued DEALLOCATE with 
TYPE(SYNC_LEVEL), and the synchronization level 
is CONFIRM. The local transaction program can 
respond by issuing either CONFIRMED or 
SEND_ERROR. 


e SEND indicates that the remote transaction program 
has entered receive state, placing the local transaction 
program in send state. This indication signals that the 
local transaction program can issue the SEND_ DATA 
verb to send data to the remote transaction program. 


REQUEST_TO SEND_ RECEIVED indicates whether 
the local LU has received a REQUEST_TO SEND 
notification. The indication is either YES or NO. 


e YES indicates that the local LU received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued REQUEST_TO_ SEND, requesting the local 
transaction program to enter receive state and place 
the remote transaction program in send state. 


e NO indicates that the local LU has not received a 
REQUEST _TO_SEND notification from the remote 
transaction program. 


State Changes: 


The following state changes occur when the 

_ RETURN_CODE indicates OK. For information on state 
changes when RETURN_CODE indicates other than OK, 
see “Understanding Basic Conversation States” on 

page 7-2. 
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e The conversation enters send state when 
WHAT RECEIVED indicates SEND. 


e The conversation enters confirm state when 
WHAT_RECEIVED indicates CONFIRM, 
CONFIRM_SEND, or CONFIRM_DEALLOCATE. 


e No state change occurs when WHAT_RECEIVED 
indicates DATA, DATA COMPLETE, or 
DATA_INCOMPLETE. 


Notes: 


1. When the transaction program specifies FILL(LL) to 
receive data in terms of logical records, the 
WHAT_RECEIVED parameter can return either the 
DATA COMPLETE or the DATA_ INCOMPLETE 
indication depending on the data received. The two 
sequences of events leading to these indications are: 


e The transaction program receives a complete 
logical record or the last portion of a record. The 
length of the record or portion of the record is 
equal to or less than the length specified on the 
MAX LENGTH parameter. The 
WHAT _ RECEIVED parameter indicates 
DATA COMPLETE. 


e The transaction program receives an incomplete 
logical record. The logical record is incomplete 
because: 


— The logical record contains more data than the 
program specifies in the MAX LENGTH 
parameter so the program receives a portion of 
the logical record equal to the specified length. 


— Only a portion of the logical record is available 
because the remote transaction program 
truncated it. The length of the truncated 
portion is less than, or equal to, the length the 
program specifies in the MAX_ LENGTH 
parameter. 
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In these two cases, the WHAT _ RECEIVED 
parameter indicates DATA INCOMPLETE. The 
transaction program issues another 
RECEIVE_IMMEDIATE or 

RECEIVE _AND_WAIT (or more than one) to 
receive the remainder of the logical record. 


For a definition of complete and incomplete logical 
records, see the description of the SEND _DATA verb. 


2. The transaction program specifies FILL(BUFFER) to 
receive data independent of its logical record format. 
This specification directs the program to receive 
whatever data is available up to the MAX LENGTH 
amount. When the program specifies FILL(BUFFER), 
it must perform its own tracking of the data’s logical 
record format. 


3. A program can use RECEIVE_IMMEDIATE with 
MAX LENGTH(0) to determine the type of 
information available without actually receiving any 
information. The RETURN_CODE and 
WHAT RECEIVED parameters indicate the type of 
information available as usual. If data is available 
and the program specified FILL(LL), the 
WHAT RECEIVED parameter indicates 
DATA INCOMPLETE. If data is available and the 
program specified FILL(BUFFER), the 
WHAT RECEIVED parameter indicates DATA. In 
either case, however, the transaction program receives 
no data. 


4. The transaction program receives only one kind of 
information at a time. For example, it may receive 
data or a CONFIRM request, but it cannot receive 
both at the same time. Also, if the remote transaction 
program truncates a logical record, the local 
transaction program receives the indication of the 
truncation from the RECEIVE. IMMEDIATE verb it 
issues after receiving the truncated record. 


The RETURN_CODE and WHAT _RECEIVED 
parameters indicate the kind of information the 
transaction program receives. 
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5. RECEIVE_IMMEDIATE resets or cancels posting. 
RECEIVE_IMMEDIATE resets posting if posting is 
active and the LU has posted the conversation. The 
verb cancels further posting if posting is active and 
the LU has not posted the conversation. For 
information about posting, see the description of the 


POST_ON_RECEIPT verb. 


6. The local transaction program usually receives a 
REQUEST_TO_SEND notification when it is in send 
state. APPC/PC reports the REQUEST_TO SEND 
notification to the program with a SEND_DATA verb 
or with a SEND_ ERROR verb it issues in send state. 
However, the program can receive the 
REQUEST_TO_ SEND notification when its 
conversation is in receive state under the following 
conditions: 


e When the local transaction program has just 
entered receive state and the remote transaction 
program issues REQUEST_TO_SEND before it 
enters send state. 


e When the remote transaction program has just 
entered receive state by issuing the 
PREPARE TO RECEIVE verb (not 
RECEIVE_IMMEDIATE), and then issuing 
REQUEST_TO_SEND before the local transaction 
program responds by entering send state. This 
ambiguity can occur because 
REQUEST_TO_SEND is an expedited request and 
this expedited request can arrive ahead of the 
request carrying the SEND indication. 


The local transaction program might not be able to 
distinguish this condition from the preceding case. 
The remote transaction program can avoid this 
ambiguity by waiting until it receives information 
from the local transaction program before it issues 


the REQUEST_TO_SEND. 


e When the remote transaction program issues the 
REQUEST_TO_SEND in send state. 
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REQUEST_TO_SEND 


Notifies the remote transaction program that the local 
transaction program is requesting to enter send state. 
APPC/PC places the conversation in send state when the 
local transaction program subsequently receives a SEND 
indication from the remote transaction program. 


Supplied Parameters: 


REQUEST_TO_SEND TP_ID (variable) 


CONV_ID (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the instance of the 
transaction program issuing this verb. The application 
subsystem receives this value from APPC/PC when it 
starts the transaction program. For more information on 
the TP_ID parameter, see “CREATE_TP” on page 5-66 or 
“TP STARTED” on page 5-58. 


CONV _ID specifies the ID of the conversation for which 
the local transaction program is requesting to enter send 
state. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The REQUEST_TO_SEND return codes are: 


e PARAMETER_CHECK 


— BAD _ TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


— BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ ID. 
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STATE_CHECK 


— R_T S NOT _RCV_STATE: The conversation is 
not in receive or confirm state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
OK. 


State Changes: 


None 


Notes: 


1, 


A transaction program enters receive state by issuing 
the PREPARE _TO_RECEIVE verb or the 

RECEIVE. AND_ WAIT verb. The remote transaction 
program enters send state after the local transaction 
program issues RECEIVE_AND_ WAIT or 
RECEIVE_IMMEDIATE, and after it receives the 
SEND indication on the WHAT_RECEIVED 


parameter. 


APPC/PC normally returns the 
REQUEST_TO_SEND_RECEIVED indication of YES 
to the remote transaction program when the 
conversation is in send state; that is, ona 
SEND_DATA or SEND_ERROR verb issued in send 
state. However, APPC/PC can also return the 
REQUEST_TO_SEND indication of YES on a 
RECEIVE _AND_WAIT or RECEIVE_IMMEDIATE 
verb. See the description of these verbs for more 
information about the REQUEST_TO SEND 
indication. 


. When the remote LU receives the 


REQUEST_TO_SEND notification, it retains the 
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notification until the remote transaction program 
issues a verb on which LU can indicate the 
notification with any verb that includes the 
REQUEST_TO_SEND_RECEIVED parameter. 


The remote LU retains only one 
REQUEST_TO_SEND notification at a time (for each 
conversation). The remote LU discards additional 
notifications until the LU can indicate the retained 
notification to the remote transaction program. 
Therefore, the local transaction program can issue the 
REQUEST_TO_SEND verb to the remote transaction 
program more times than the remote LU indicates. 
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SEND_DATA 


Sends one data record to the remote transaction program. 
The data format consists of logical records but the amount 
of data that this verb sends is independent of the data 
format. 

Supplied Parameters: 

SEND_DATA TP_ID (variable) 
CONV_ID (variable) 
DATA_LENGTH (variable) 


DATA (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
(NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is sending the data. 


DATA_LENGTH specifies the length of the data the 
local transaction program is sending. This data length 
has no relation to the length of a logical record. 
APPC/PC uses this information only to determine the 
length of the data at the location specified by the DATA 
parameter. 


Values between 0 and 65535 are valid for this parameter, 
but the sum of this value and the offset portion of the 
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DATA address must not exceed 65535. This limit prevents 
the data from crossing a segment boundary. 


If the transaction program specifies a data length value of 
0, the local LU does not send any data. In this case, 
APPC/PC ignores the DATA parameter. 


DATA specifies the variable containing the data record 
that the transaction program is sending. The data may 
include multiple records or part of a record. Each logical 
record consists of a 2-byte length field (denoted as LL) 
followed by a data field; the length of the data field can 
range from 0 to 32765 bytes. The 2-byte length field 
contains the 15-bit binary length of the record, and a 
high-order bit. The LU ignores this high-order bit when 
performing basic conversations (the LU’s mapped 
conversation component uses this bit to support the 
mapped conversation verbs). 


The length of the record includes the 2-byte length field; 
that is, a record is 2 bytes longer than the length of the 
data. For this reason, record length values of X’0000’, 
X’0001’, X’8000’, and X’8001’ are invalid. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The SEND_ DATA return codes are: 


e PARAMETER CHECK 


~ BAD _TP_ID: APPC/PC does not recognize the 
specified TP_ ID. 


—- BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


—- DATA AREA ACROSS SEGMENT: The data to 
be sent crosses a segment boundary. 


— BAD_LL: The DATA parameter contains an 


invalid logical record length (LL) value of X’0000’, 
X’0001’, X’8000’, or X’8001’. 
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STATE_CHECK 


—~ SEND DATA NOT_SEND_ STATE: The 
conversation is not in send state. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_ PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_ TIMER 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_PURGING 
SVC_ERROR_PURGING. 


REQUEST_TO_SEND_RECEIVED indicates whether 
the local LU has received a REQUEST _TO_SEND 
notification. The indication is either YES or NO. 


YES indicates that the local LU has received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued REQUEST_TO_ SEND, requesting the local 
transaction program to enter receive state and place 
the remote transaction program in send state. 


NO indicates that the local LU has not received a 
REQUEST _TO_SEND notification from the remote 
transaction program. 


State Changes: 


The state of the conversation does not change when 
RETURN_CODE indicates OK. For information on state 
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changes when RETURN_CODE indicates other than OK, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5. 


Notes: 


1. The data sent by the transaction program consists of 
logical records. The DATA LENGTH parameter of 
the SEND_ DATA verb determines the amount of data 
a program sends when it issues this verb. This amount 
of data is independent of the length of the logical 
records. That is, the data may consist of one or more 
complete records, the beginning of a record, the middle 
of a record, or the end of a record. The following 
combinations of complete and partial records are also 
possible: 


e One or more complete records, followed by the 
beginning of a record 


e The end of a record, followed by one or more 
complete records 


e The end of a record, followed by one or more 
complete records, followed by the beginning of a 
record 


e The end of a record, followed by the beginning of a 
record. 


2. A complete logical record contains the 2-byte LL field 
followed by the number of data bytes the program 
specifies in the LL field. (A value of 2 in the LL field 
specifies that the complete logical record contains only 
the 2-byte length field.) 


An incomplete logical record contains any amount of 
data less than a complete record. It can consist of 
only the first byte of the 2-byte LL field, the LL field 
plus all of the data field except the last byte, or any 
amount in between. A logical record remains 
incomplete until the program sends the last byte of the 
data field. 
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If the value of the LL field is 2 (indicating a data field 
of 0-length), the logical record is complete after the 
transaction program sends the second byte of the LL 
field. 


The transaction program must finish sending a logical 
record before it can issue any of the following verbs: 


CONFIRM 

DEALLOCATE with TYPE(FLUSH) 
DEALLOCATE with TYPE(SYNC_LEVEL) 
PREPARE_TO_ RECEIVE 
RECEIVE_AND_WAIT. 


A transaction program finishes sending a logical 
record when it sends a complete record or when it 
truncates an incomplete record. 


. A program can truncate an incomplete logical record 


by issuing the SEND_ERROR verb. When the LU 
receives the SEND ERROR verb, it flushes its buffer 
and sends whatever portion of a logical record it has 
accumulated before the program issues the 
SEND_ERROR verb. The LU then treats the first 2 
bytes of data specified in the next SEND DATA as the 
LL field for the next record. 


The program can also truncate an incomplete logical 
record by issuing DEALLOCATE with 
TYPE(ABEND_PROG), TYPE(ABEND_ SVC), or 
TYPE(ABEND_ TIMER). 


The LU retains the data from the program until it 
accumulates (from one or more SEND_DATA verbs) a 
sufficient amount for transmission, or until the 
program issues a verb that forces the LU to flush its 
send buffer. The amount of data that is sufficient for 
transmission depends on the characteristics of the 
session allocated for the conversation. This amount 
varies from one session to another. 


When the REQUEST_TO_ SEND RECEIVED 
parameter indicates YES, the remote transaction 
program is requesting that the local transaction 
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program enter receive state and place the remote 
transaction program in send state. A transaction 
program enters receive state by issuing the 
PREPARE _ TO_RECKEIVE verb or the 
RECEIVE_AND_ WAIT verb. The partner transaction 
program enters send state after it issues the 

RECEIVE _AND_WAIT verb or the 

RECEIVE IMMEDIATE verb, and receives the SEND 
indication from its partner transaction program on the 
WHAT RECEIVED parameter. 
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SEND_ERROR 


Informs the remote transaction program that the local 
transaction program detected an error. If the 
conversation is in send state, the LU flushes its send 


buffer. 


After the successful completion of this verb, the local 
transaction program is in send state and the remote 
transaction program is in receive state. The transaction 
program must take the appropriate actions to correct the 
problem. 


Supplied Parameters: 
SEND_ERROR TP_ID (variable) 
CONV_ID (variable) 


TYPE (PROG) 
(SVC) 


LOG_DATA_LENGTH (variable) 


LOG_DATA (variable) 
Returned Parameters: 


RETURN_CODE (variable) 


REQUEST_TO_SEND_RECEIVED (YES) 
NO) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


CONV_ID specifies the ID of the conversation on which 


the local transaction program is notifying the remote 
transaction program of an error. 
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TYPE specifies the type of error being reported. A 
normal transaction program should use PROG. Programs 
that provide services to transaction programs should use 
SVC. 


LOG_DATA_LENGTH specifies the number of bytes of 
log data to be sent. Set this parameter to 0 if there is no 
log data. The parameter must be 0 for any TYPE value 
except ABEND_PROG, ABEND_SVC or 
ABEND_TIMER. Values between 0 and 65535 are valid 
for this parameter, but the sum of this value and the offset 
of the LOG_DATA address must not exceed 65535. This 
limit prevents the log data from crossing a segment 
boundary. 


LOG_DATA specifies the variable (consisting of a single 
LL) containing transaction program error information 
that APPC/PC is to send to the partner LU. The partner 
LU either discards the data or saves it in a system error 
log. (For a description of how APPC/PC passes 
LOG_DATA it receives to the application subsystem, see 
“Managing Logged Errors (SYSLOG Exit)” on page 2-10. 
The transaction program must format this error 
information as an error log GDS variable (for the correct 
format, see “GDS Variables” in the SNA Reference 
Summary). 


Returned Parameters: 

RETURN_CODE indicates the result of verb execution. 
APPC/PC can-return the following return codes in any 
conversation state: 


e PARAMETER _CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


- BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— DATA_AREA_ ACROSS_SEGMENT: The log 


data area crosses a segment boundary. 
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—- LOG_LL_WRONG: The LL field of the log data 
does not match the specified 
LOG_DATA_LENGTH. 


— BAD TYPE: APPC/PC does not recognize the 
specified TYPE. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK. 


The following return codes can occur when the 
transaction program issues SEND _ERROR and the 
conversation is in send state. For detailed information on 
these return codes, see “Understanding Basic 
Conversation Return Codes” on page 7-5 and 

Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
CONV_FAILURE_NO_ RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
PROG_ERROR_PURGING 
SVC_ERROR_PURGING. 


The following return codes can occur when the 
transaction program issues SEND_ERROR and the 
conversation is in receive state. For detailed information 
on these return codes, see “Understanding Basic 
Conversation Return Codes” on page 7-5 and 

Appendix C, “Verb Return Codes.” 


e CONV_FAILURE_NO_RETRY 
e CONV_FAILURE_RETRY 
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e DEALLOCATE_NORMAL. 


The following return codes can occur when the 
transaction program issues SEND_ERROR and the 
conversation is in confirm state. For detailed information 
on these return codes, see “Understanding Basic 
Conversation Return Codes” on page 7-5 and 

Appendix C, “Verb Return Codes.” 


e CONV_FAILURE_NO_RETRY 
e CONV_FAILURE_RETRY. 


REQUEST_TO_SEND_RECEIVED indicates whether 
the local LU has received a REQUEST _TO SEND 
notification. The indication is either YES or NO. 


e YES indicates that the local LU has received a 
REQUEST_TO_SEND notification from the remote 
transaction program. The remote transaction program 
has issued REQUEST _TO SEND, requesting the local 
transaction program to enter receive state and place 
the remote transaction program in send state. 


e NO indicates that the local LU has not received a 
REQUEST _TO_SEND notification. 


State Changes: 


The following state changes can occur if RETURN_CODE 
indicates OK. For information on state changes when 
RETURN_CODE indicates other than OK, see 
“Understanding Basic Conversation States” on page 7-2. 


The conversation enters send state when the transaction 
program issues the verb in receive or confirm state. No 
state change occurs when the program issues 
SEND_ERROR in send state. 


Notes: 
1. The LU retains the error notification and log data in 
its send buffer until it accumulates enough 


information for transmission, or until the local 
transaction program issues a verb that causes the LU 
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to flush its send buffer. The amount of information 
that is sufficient for transmission depends on the 
characteristics of the session allocated for the 
conversation. This amount can vary from one session 
to another. 


APPC/PC reports the SEND_ERROR to the remote 
transaction program as one of the following return 
codes (based on the TYPE parameter). 


For detailed information on these return codes, see 
“Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


When the local transaction program issues 
SEND_ERROR in receive state, APPC/PC purges 
incoming information including return code 
indications. After purging these return code 
indications, APPC/PC reports others in their place. 


APPC/PC reports DEALLOCATE NORMAL for the 


following purged return code indications. 


e ALLOCATION_ERROR 
e DEALLOCATE_ABEND_ PROG 
e DEALLOCATE_ABEND_SVC 

e DEALLOCATE_ABEND_TIMER. 


APPC/PC reports OK for the following purged return 
code indications. 


e PROG_ERROR_PURGING 
e SVC_ERROR_PURGING. 


The other kinds of incoming information that 
APPC/PC can purge are: 
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e Data that a program sends by issuing the 
SEND_DATA verb 


e Confirmation requests that a program sends by 
issuing the CONFIRM verb. 


If the transaction program sends a confirmation 
request in conjunction with the DEALLOCATE verb 
by specifying the TYPE(SYNC_LEVEL) parameter, 
APPC/PC also purges the deallocation request. 


APPC/PC does not purge an incoming 
REQUEST_TO_SEND indication. When the 
transaction program issues a verb that includes the 
REQUEST_TO_SEND_RECEIVED parameter, it 
receives the REQUEST _TO_SEND indication on this 
parameter. 


4. The transaction program may use the SEND ERROR 
verb for various application-level functions. For 
example, the program can issue this verb to truncate 
an incomplete logical record it is sending, to inform 
the remote program of an error it detected in data it 
received, or to reject a confirmation request. 


5. The SEND_ERROR verb resets or cancels posting. 
This verb resets posting if posting is active and the LU 
has posted the conversation. The SEND_ERROR verb 
cancels posting if posting is active and the LU has not 
posted the conversation. Further posting will not 
occur. (For information on posting, see the description 
of the POST_ON__RECEIPT verb.) 


6. LOG_DATA_ LENGTH specifies the number of bytes 
of log data to be sent. Set this parameter to 0 if there 
is no log data. The parameter must be 0 for any TYPE 
value except ABEND PROG, ABEND_ SVC or 
ABEND_ TIMER. Values between 0 and 65535 are 
valid for this parameter, but the sum of this value and 
the offset of the LOG_DATA address must not exceed 
65535. This limit prevents the log data from crossing a 
segment boundary. 


7-88 SEND_ERROR 


TEST 


Tests the specified conversation for a condition. The 
return code indicates the result of the test. 


Supplied Parameters: 
TP_ID (variable) 


CONV_ID (variable) 


TEST (POSTED) 
(REQUEST_TO_SEND_RECEIVED) 


Returned Parameters: 


RETURN_CODE (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP_STARTED” on 
page 5-58. 


CONV _ID specifies the ID of the conversation on which 
the local transaction program is performing the test. 


TEST specifies the condition to be tested. 


e POSTED tests whether the LU has posted the 
conversation. Before posting can occur, the program 
must have issued the POST_ON_ RECEIPT verb. The 
return code indicates whether posting has occurred, as 
follows: 


— OK indicates that the LU has posted the 
conversation and that posting is now reset. The 
transaction program should issue 
RECEIVE _AND_ WAIT or 
RECEIVE IMMEDIATE to receive the 
information waiting in the receive buffer of the 
local LU. 
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— UNSUCCESSFUL indicates that the conversation 
is in receive state but the LU has not posted the 
conversation. 


— POSTING _NOT_ACTIVE indicates that posting is 
not active for the specified conversation. 


e REQUEST_TO_SEND_RECEIVED tests whether 
the local LU has received a REQUEST_TO SEND 
notification from the remote transaction program. The 
return code indicates the results of this test as follows: 


— OK indicates that the LU has received a 
REQUEST_TO_SEND indication. The remote 
transaction program has issued 
REQUEST_TO_ SEND, requesting the local 
transaction program to enter receive state and 
place the remote transaction program in send state. 


— UNSUCCESSFUL indicates that the LU has not 
received a REQUEST_TO_SEND indication. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The TEST return codes other than those described above 
are: 


e OK 


— POSTED_DATA: The LU has posted the 
conversation and data is available in the LU’s 
receive buffer. 


— POSTED NOT_DATA: The LU has posted the 
conversation and information other than data is 
available in the LU’s receive buffer. 


e PARAMETER CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 
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- BAD _CONV_ID: APPC/PC does not recognize the 
specified CONV_ID. 


— TEST_INVALID_TYPE: APPC/PC does not 
recognize the specified TYPE. 


STATE_CHECK 


— NOT _RCV_STATE: The conversation is not in 
recelve state and the transaction program specified 
the POSTED option for the TYPE parameter. 


DATA _ POSTING BLOCKED: APPC/PC does not 
have sufficient storage space to permit posting one of 
the active conversations. This error does not cause 
APPC/PC to reset or cancel posting. The transaction 
program can continue issuing verbs, but to provide 
sufficient space for further posting it should issue 
RECEIVE_IMMEDIATE or RECEIVE_ AND_ WAIT 
to free some space. Alternatively, the program can 
issue DEALLOCATE_ABEND to terminate a 
conversation. 


If you use receive pacing and issue a TEST or WAIT 
for more than R(P-1) bytes of data (where P = the 
receive pacing window, and R = the negotiated 
maximum RU size for the session), APPC/PC may 
report a buffer full condition with this return code. 
Even this amount of data may be too large if the 
partner transaction program issues the FLUSH verb 
between SEND_DATA verbs, causing messages of less 
than the maximum RU size to flow on the line. 

Posting is blocked if the allotted session buffers are 
filled for the conversation being posted. If you need to 
test for more data than this amount, reconfigure 
APPC/PC and increase the pacing window size or do 
not use pacing. If you increase the pacing window size 
you must also increase the workspace size accordingly. 
However, if receive pacing is not used, APPC/PC will 
have no control of data sent from the partner 
transaction program. If its workspace becomes full 
APPC/PC abnormally terminates and rejects 
subsequent verbs. 
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For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_ TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. ‘ 


State Changes: 
None 
Notes: 


1. The transaction program can use this verb in 
conjunction with POST_ON RECEIPT. Using 
POST_ON_RECEIPT with this verb enables a 
transaction program to continue its processing while 
waiting for information to become available. The 
program can issue POST_ON_RECEIPT for one or 
more conversations and then periodically issue the 
TEST verb for each conversation to determine when 
information is available in the receive buffer of the 
local LU. 


2. Posting is active for a conversation if the transaction 
program has issued the POST_ON_ RECEIPT verb for 
that conversation and posting has not been reset or 
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canceled. (For information on posting, see the 
description of the POST_ON_RECEIPT verb). 


. The remote transaction program sends a 


REQUEST_TO_SEND notification to request the 
local transaction program to enter receive state and 
place the remote transaction program in send state. 

To enter receive state, a program issues either 
RECEIVE _AND_WAIT or PREPARE TO_RECEIVE. 
The partner transaction program enters send state 
when the local transaction program issues either the 
RECEIVE _AND_WAIT verb or the 
RECEIVE_IMMEDIATE verb and receives the SEND 
indication on the WHAT_RECEIVED parameter. 
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WAIT 


Waits for posting to occur on any basic conversation 
included in a list of conversations specified with this verb. 
Posting a conversation occurs when posting is active for 
the conversation and the LU has any information that the 
transaction program can receive, such as data, 
conversation status, or a request for confirmation. 


Supplied Parameters: 
TP_ID (variable) 
CONV_ID_LIST (variablel, variable2, 


Returned Parameters: 


RETURN_CODE (variable) 


CONV_POSTED (variable) 


Supplied Parameters: 


TP_ID specifies the identifier for the transaction program 
issuing this verb. The application subsystem receives this 
value from APPC/PC when it starts the transaction 
program. For more information on the TP_ID parameter, 
see “CREATE_TP” on page 5-66 or “TP STARTED” on 
page 5-58. 


CONV_ID_LIST specifies the ID of each of the 
conversations that the LU can post. 


e variablel, variable2, ... are the individual 
conversation IDs. The transaction program can 
specify one or more CONV_IDs in this list. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The WAIT return codes are: 


e OK: The LU has posted one of the conversations in 
the CONV_ID_LIST. 
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— POSTED_DATA: The LU has posted a 
conversation and data is available in the LU’s 
receive buffer. 


— POSTED _NOT_ DATA: The LU has posted a 
conversation and information other than data is 
available in the LU’s receive buffer. 


PARAMETER_CHECK 


— BAD_TP_ID: APPC/PC does not recognize the 
specified TP_ID. 


—- BAD _CONV_ID: APPC/PC does not recognize one 
of the CONV_ID values specified by 
CONV_ID_LIST. 


STATE_CHECK 


— NOT _RCV_STATE: One of the conversations in 
the CONV_LIST is not in receive state. 


POSTING_NOT_ACTIVE: Posting is not active for 
any of the conversations in the CONV_ID_LIST. 


DATA POSTING BLOCKED: One of the active 
conversations cannot be posted because the APPC/PC 
internal storage is temporarily being used. The local 
program cannot send a pacing response. This error 
does not cause APPC/PC to reset or cancel posting. 
The transaction program can continue issuing verbs, 
but to provide sufficient space for further posting, it 
should issue RECEIVE_ IMMEDIATE or 

RECEIVE AND_WAIT to free some space. 
Alternatively, the program can issue 
DEALLOCATE(TYPE = ABEND_ PROG) to terminate 
a conversation. 


If you use receive pacing and issue a TEST or WAIT 
for more than R(P-1) bytes of data (where P = the 
receive pacing window, and R = the negotiated 
maximum RU size for the session), APPC/PC may 
report a buffer full condition with this return code. 
Even this amount of data may be too large if the 
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partner transaction program issues the FLUSH verb 
between SEND_DATA verbs causing messages of less 
than the maximum RU size to flow on the line. 

Posting is blocked if the allotted session buffers are 
filled for the conversation being posted. If you need to 
test for more data than this amount, reconfigure 
APPC/PC and increase the pacing window size or do 
not use pacing. If you increase the pacing window 
size, you must also increase the workspace size 
accordingly. However, if receive pacing is not used, 
APPC/PC will have no control of data sent from the 
partner transaction program. If its workspace becomes 
full APPC/PC abnormally terminates and rejects 
subsequent verbs. 


For detailed information on the following return codes, 
see “Understanding Basic Conversation Return Codes” on 
page 7-5 and Appendix C, “Verb Return Codes.” 


ALLOCATION_ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_ TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_ VERB 
PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


CONV_POSTED: indicates the CONV_ID of the posted 
(or blocked) conversation. 
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UNSUCCESSFUL indicates that APPC/PC could not 
successfully execute the function of the verb, or that the 
requested data or notification was not yet available. 
APPC/PC reports this return code to the local program on 
the verb issued. The state of the conversation remains 
unchanged. 


State Changes: 
None 
Notes: 


1. A transaction program can use this verb with the 
POST_ON_RECEIPT verb to receive information from 
multiple conversations in a synchronous fashion. The 
program must issue POST_ON_ RECEIPT for each of 
the conversations and then issue WAIT for all of these 
conversations to wait until the LU has information for 
the program to receive from one or more of the 
conversations. 


2. Posting may not be active for all of the conversations 
included in the CONV_LIST. This WAIT verb waits 
for posting to occur only on the conversations for 
which posting is active. If posting is not active for 
any of the conversations included in the CONV_LIST, 
APPC/PC reports the POSTING_NOT_ACTIVE 
return code to the program. 


3. Posting is active for a conversation if the transaction 
program has issued the POST_ON_RECKEIPT verb for 
that conversation and posting has not been reset or 
canceled. (For information on posting, see the 
description of the POST_ON_RECEIPT verb). 


4. The return code OK indicates that the LU has posted 
one of the conversations included in the CONV_LIST 
for which posting is active. This return code also 
indicates that posting for that conversation is now 
reset. APPC/PC returns the CONV_ID of the posted 
conversation with the CONV_POSTED parameter. 
The transaction program should issue 
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RECEIVE_AND_ WAIT or RECEIVE_IMMEDIATE 
to receive the information from a posted conversation. 
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Chapter 8. Using the Network 
Management Verb 


A fundamental capability of SNA is to manage a node or a 
network of nodes. SNA also provides facilities that an 
operator (programmed or human) can use to manage an 
SNA node or network of nodes. 


A transaction program uses the TRANSFER MS DATA 
verb to provide management services information to a 
network management services function (that is, an SSCP). 


The SSCP can use this information to manage the 
network to which this node is connected. 


Understanding the Network 
Management Verb 


The TRANSFER _MS_ DATA verb builds and sends an 
unsolicited Network Management Vector Transport 
(NMVT) RU to a network management services function. 
A transaction program can also use the 
TRANSFER MS_ DATA verb to log user-defined data. 
Transaction programs can provide the following NMVT 
vector information to APPC/PC: 


e Alerts 
e Problem determination statistics (PDSTATS) 
e Other network management data. 


For information on the specific format of the NMVT RU, 
see the SNA Reference Summary. 
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Alerts 


Alerts notify the control point management services that a 
system conversation is unavailable (or will soon become 
unavailable) to end users. An alert is the primary method 
that a transaction program can use to communicate 
problem determination information to the network 
operator. 


Problem Determination Statistics 


PDSTATS provide the SNA control point management 
services with error-rate data for communication links. 
This information assists the control point management 
services in determining and diagnosing problems 
associated with communication links. 


Verb Description 


TRANSFER _MS_ DATA 


Supplied Parameters: 


TRANSFER_MS DATA DATA_TYPE (USER_DEFINED) 
(NMVT ) 
(ALERT _SUBVECTORS ) 
(PDSTATS_SUBVECTORS ) 


CORRELATOR_SUBVECTOR (ADD) 
(NO_ADD) 


PRODUCT_SET_ID_SUBVECTOR 
(ADD) 
(NO_ADD) 


SYSLOG (LOG) 
(NO_LOG) 


SSCP_PU_SESSION (SEND) 
(NO_SEND) 


DATA_LENGTH (variable) 


DATA (variable) 


Returned Parameters: 
RETURN_CODE (variable) 


Supplied Parameters: 


DATA_TYPE specifies the variable that the transaction 
program uses to define the type of data it is providing. 
The valid data types are: 


e USER_DEFINED specifies that the data is user 
defined. APPC/PC logs this data and does not send it 
on the SSCP-PU session. 


e NMVT specifies that the data contains a complete 
NMVT. The data must include the Network Services 
(NS) header, the major Network Management Vector, 
and the appropriate subvectors. 
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e ALERT SUBVECTORS specifies that the data 
contains management services information for an alert, 
in the format appropriate for an alert. (For specific 
details on alerts, see the SNA Reference Summary.) 
The data consists of the RU without the NMVT or the 
NS header which APPC/PC adds automatically. 


e PDSTATS_SUBVECTORS specifies that the data 
contains management services information for problem 
determination statistics (PD Stats) in the format 
appropriate for this subvector. (For details on the 
formats for the PD Stats, see the SNA Reference 
Summary.) The data consists of the RU without the 
NMVT or the NS header which APPC/PC adds 


automatically. 


CORRELATOR _SUBVECTOR specifies whether 
APPC/PC is to add the CORRELATOR subvector (X’42’) 
to the NMVT. This parameter applies to all of the options 
identified by the DATA_TYPE parameter. 


The two options for this parameter are: 


e ADD directs APPC/PC to add the CORRELATOR 
subvector to the NMVT. 


e NO_ADD directs APPC/PC not to add the 
CORRELATOR subvector to the NMVT. 


PRODUCT_SET_ID_SUBVECTOR specifies whether 
APPC/PC adds the Product Set ID Subvector (X’10’) to the 
data. Network management services use this information 
to identify the sender of the alert and the alerted 
conversation. This parameter applies to all of the entities 
identified by DATA_ TYPE, except USER_DEFINED. 
APPC/PC ignores this parameter if the program specifies 
DATA_TYPE(USER_DEFINED). The two options for 
this parameter are: 


e ADD directs APPC/PC to add the Product Set ID 
Subvector. 


e NO_ADD directs APPC/PC not to add the Product Set 
ID Subvector. 
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SYSLOG specifies whether APPC/PC is to transfer the 
data to the PU SYSLOG exit. (For more information, see 
“ATTACH PU” on page 5-17.) The two options for this 
parameter are: 


e LOG directs APPC/PC to transfer the log data to the 
PU syslog exit. 


e NO_LOG directs APPC/PC not to transfer the log 
data to the PU syslog exit. 


SSCP_PU_SESSION specifies whether or not APPC/PC 
is to send the data on the SSCP-PU session. APPC/PC 
logs the data if the program specifies not to send the data. 
APPC/PC also logs the data if the program specifies to 
send the data, but the SSCP-PU session is not active. 
APPC/PC ignores this parameter if the program specifies 
DATA _TYPE(USER_DEFINED). Therefore, the program 
cannot send user-defined data on the SSCP-PU session. 
The two options for this parameter are: 


e SEND directs APPC/PC to send the data on the 
SSCP-PU session. 


e NO_SEND directs APPC/PC not to send the data on 
the SSCP-PU session. 


DATA _LENGTH specifies the number of data bytes the 
program is sending (including the LL field). All data, 
including fields that APPC/PC adds, must fit within one 
RU (as specified for the adapter on the APPC/PC 
configuration menu). 


DATA specifies the variable containing the management 
services data or the user-defined data that the program is 
sending. When the program specifies the TYPE(NMVT) 
this data includes only LL fields; APPC/PC adds the 
headers. 


Returned Parameters: 


RETURN_CODE indicates the result of verb execution. 
The TRANSFER _MS_ DATA return codes are: 
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e APPC_ABENDED indicates that APPC/PC has been 
abnormally terminated. 


e APPC_BUSY indicates that APPC/PC is executing 
another verb and cannot execute this verb. This error 
can occur if a verb is issued after APPC/PC execution 
is interrupted (for example, by a Ctrl-Break or timer 
interrupt). 


e APPC_DISABLED indicates that APPC/PC is disabled 
by the DISABLE/ENABLE_APPC verb. 


e DATA EXCEEDS _ RU_SIZE indicates that the data 
length exceeded the allowable RU size. 


e OK indicates that APPC/PC executed the verb 
successfully. 


e SSCP_PU_SESSION_NOT_ACTIVE indicates that 
APPC/PC could not send the NMVT because the 
SSCP-PU session was not active. 
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Chapter 9. Other APPC/PC 
Services 


APPC/PC provides additional services for the convenience 
of the programmer. These functions include: 


e A passthrough capability which enables an application 
subsystem to define its own verbs using the same 
interrupt vector as APPC/PC. 

e An ASCII/EBCDIC conversion service. 


e The ability to trace API invocations and sent and 
received messages. 


e The ability to disable and re-enable the operation of 
APPC/PC. 
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Verb Descriptions 


The descriptions of the verbs that provide these services 
are as follows: 


SET_PASSTHROUGH 


The SET PASSTHROUGH verb provides the address of 
an exit to which APPC/PC branches when the application 
subsystem issues the PASSTHROUGH verb. This exit 
enables a transaction program to issue verbs to the 
application subsystem, using the same interrupt X’68’ 
mechanism used by APPC/PC verbs. The exit procedure 
may itself issue further verbs. 


Unlike most verbs, the program must define the 
information for the SET_PASSTHROUGH verb entirely 
within registers; there is no verb structure. 


Supplied Parameters: 


SET_PASSTHROUGH PASSTHROUGH_ADDRESS (variable) 


Supplied Parameters: 


PASSTHROUGH_ADDRESS specifies the exit address 
to which APPC/PC branches when the program issues the 
PASSTHROUGH verb. 
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PASSTHROUGH 


Permits an application subsystem to define its own verbs 
using the interrupt vector X’68’. APPC/PC ignores these 
user-defined verbs as it passes them through to the 
application subsystem. 


When the program issues the PASSTHROUGH verb, 
APPC/PC performs a far branch (not a call) to the 
specified exit procedure. APPC/PC leaves hardware 
interrupts inhibited and registers untouched. The 
application subsystem uses the SET_PASSTHROUGH 
verb to specify the address of the exit procedure. 


The exit procedure may itself issue APPC/PC verbs. 


The PASSTHROUGH verb enables a program to access 
application subsystem services without using another 
software interrupt. The application subsystem must define 
its own verbs for transaction programs to access through 
this verb. 
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CONVERT 


CONVERT provides a utility service for ASCII/EBCDIC 
conversion. This verb operates on a specified character 
string to produce a converted character string. 


APPC/PC assumes that all names that a program passes 
over the interrupt X’68’ interface use EBCDIC coding. 
Therefore, programs that use ASCII coding for APPC/PC 
names (LU names, TP names, passwords, and so on) must 
convert these names to EBCDIC. Conversely, the 
application subsystem may need to convert incoming 
names from EBCDIC to ASCII. 


A program may also need to perform data conversion if it 
is communicating with a node that expects EBCDIC data. 


Appendix H, “ASCII/EBCDIC Translation Tables” 
provides the tables APPC/PC uses to convert data from 
EBCDIC to ASCII and ASCII to EBCDIC. You can 
specify your own (type G) conversion table on the 
APPC/PC configuration menus. 


Supplied Parameters: 


DIRECTION (ASCII_TO_EBCDIC) 
(EBCDIC_TO_ASCITI) 


CONVERT 


LENGTH (variable) 


SOURCE (variable) 


TARGET (variable) 


CHARACTER _SET (AE) 


Returned Parameters: 
RETURN_CODE (variable) 


9-4 CONVERT 


Supplied Parameters: 


DIRECTION specifies whether conversion is ASCII to 
EBCDIC or EBCDIC to ASCII. The two options for this 


parameter are: 


e ASCII_TO_EBCDIC: Directs APPC/PC to convert 
ASCII characters to EBCDIC. 


e EBCDIC_TO ASCII: Directs APPC/PC to convert 
EBCDIC characters to ASCII. 


LENGTH specifies the number of characters in the string 
APPC/PC is to convert. 


SOURCE specifies the variable containing the string 
APPC/PC is to convert. 


Warning: The sum of the SOURCE offset and the 
LENGTH must be less than 65535 to prevent the area for 
the SOURCE string from overlapping a segment boundary. 


TARGET specifies the variable that is to receive the 
converted character string. 


Warning: The sum of the TARGET offset and the 
LENGTH must be less than 65535 to prevent the area for 
the TARGET string from overlapping a segment boundary. 


If the program does not need to preserve the source string, 
it can specify the same variable for the SOURCE and 
TARGET parameters. 


CHARACTER _ SET enables the program to specify the 
set of characters permitted in the source string. The 
options for this parameter are: 


e Type AE: Permits the source string to include 
lowercase a-z; uppercase A-Z; numerics 0-9; and special 
characters $, #, @, and the period (.). This option does 
not place any restrictions on the first character in the 
source string; it also permits the string to include 
trailing blanks. 
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Type A: Permits the source string to include 
uppercase A-Z; numerics 0-9; and special characters $, 
#, and @. In the ASCII to EBCDIC direction, the type 
A option accepts lowercase characters and converts 
them to uppercase EBCDIC characters. This option 
requires the first character of the string to be an 
uppercase letter or one of the three special characters. 
The type A option also permits the source string to 
include trailing blanks. 


Type G: This option permits the source string to 
include any character. APPC/PC converts the source 
string according to the conversion code table that you 
specify on the APPC/PC configuration menus. If no 
such table exists, the program should not specify type 
G conversion. 


Returned Parameters: 


RETURN_CODE indicates whether the conversion was 
successful. 


APPC_ABENDED indicates that APPC/PC has been 


abnormally terminated. 


CONVERSION_ERROR indicates that the program 
specified the CHARACTER _SET(A) or 

CHARACTER SET(AE) parameter and APPC/PC 
encountered one or more characters in the source 
string that are not defined in the selected conversion 
table. APPC/PC converts undefined characters to 
X’00’. This error cannot occur if the program specifies 
the CHARACTER SET(G) parameter. 


INVALID DIRECTION indicates that APPC/PC does 
not recognize the specified DIRECTION. 


INVALID_FIRST_CHARACTER indicates that the 
program specified the CHARACTER_SET(A) 
parameter and the first character in the source string 
does not satisfy the requirements of this character set 
specification. 
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INVALID_TYPE indicates that APPC/PC does not 
recognize the specified CHARACTER_SKET type. 


OK indicates that the code conversion was successful. 


SEGMENT OVERLAP indicates that the area 
specified for either the source or target string area 
overlaps a segment boundary. 


TABLE_ERROR indicates that APPC/PC could not 
locate the type G conversion table. 
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TRACE 


TRACE enables or disables the APPC/PC tracing 
function. After a program enables tracing, APPC/PC can 
trace verbs through the API, and trace sent and received 
messages above the adapter layer. APPC/PC passes trace 
parameters in registers instead of using a control block. 
The program can direct APPC/PC to display, print, file, or 
save trace messages in a storage buffer. APPC/PC uses 
ASCII coding for trace messages. 


Supplied Parameters: 
TRACE MESSAGES (ON (TRUNC(variable) )) 
(OFF) © 


TRACE API (ON) 
(OFF) 


TRACE DESTINATION (DISPLAY) 
(PRINTER) 
(STORAGE 
TRACE STATS (variable) ) 
(FILE 
TRACE _STATS (variable) ) 


Supplied Parameters: 


TRACE MESSAGES directs APPC/PC to enable or 
disable tracing. The two options for this parameter are 
ON and OFF. The ON specification includes a TRUNC 
specification that determines how many characters of a 
message the trace can return. 


e ON directs APPC/PC to begin tracing sent and 
received messages. 


In addition to the messages, a trace indicates when a 
link becomes active by returning LINK CONNECTED. 
When the link becomes inactive because of a link 
error, the trace indicates LINK INOPERATIVE. 


TRUNC specifies the maximum number of characters 


in the RU portion of the trace that APPC/PC is to 
return. APPC/PC truncates any characters exceeding 
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this maximum number. A value of 0 specifies that 
APPC/PC should not truncate the RU portion of the 
trace. 


OFF directs APPC/PC to stop tracing messages. 


TRACE_API enables and disables the tracing of verbs 
passing through the API. The two options for this 
parameter are ON and OFF. 


ON: Directs APPC/PC to trace verbs passed through 
the API. 


This option returns the first 64 bytes of each traced 
verb in hexadecimal format. 


OFF: Stops the tracing of verbs passed through the 
API. 


TRACE_DESTINATION determines whether APPC/PC 
directs the tracing output to the IBM PC screen, printer, 
storage, or a file. A program can specify more than one 
destination for the tracing output. The options for this 
parameter are: 


DISPLAY: Directs APPC/PC to display the trace 
output on the IBM PC screen. The operator can stop 
and restart the display of the trace output by pressing 
the Scroll Lock key. 


PRINTER: Directs APPC/PC to send the trace output 
to the IBM PC printer (LPT1:). The operator can stop 
and restart the display of the trace output by pressing 
the Scroll Lock key. 


STORAGE: Directs APPC/PC to place the trace 
output in internal storage. This option requires the 
application subsystem to provide a routine for printing 
the trace output stored in this buffer. This option 
stores 80 character records, the last two characters of 
which are carriage return and line feed (X’0D0A’). 


When the program directs APPC/PC to place the trace 
output in an internal storage buffer, it must also 
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include certain information in the TRACE _STATS 
parameter area of the TRACE verb. The 
TRACE _ STATS parameter area must provide the 
address of the buffer that is to receive the trace 
output, the maximum number of records to place in the 
buffer, and an initialized space for trace statistics. For 
a description of the contents of the TRACE _STATS 
buffer, see the description of the TRACE verb in 
Appendix A, “Verb Operation Codes and Formats.” 


After the trace output fills the buffer with the specified 
maximum number of records, it wraps around to begin 
placing new records at the front of the buffer again. 


e FILE: Directs APPC/PC to place the trace output in a 
file named OUTPUT.PC (in the same directory as 
APPC/PC). 


When the program directs APPC/PC to place the trace 
output in a file, it must also include certain 
information with the TRACE_STATS parameter area 
of the TRACE verb. For the FILE option, the 
TRACE_STATS parameter area must provide the 
maximum number of records to place in the file, and 
an initialized space for trace statistics. After the trace 
output fills the file with the specified maximum 
number of records, it wraps around to begin placing 
new records at the front of the file again. 


The following table illustrates the tracing formats for API 


Entry Format, API Return Format, Sent Message Format, 
and Received Message Format: 


Tracing Message Formats 


APT Entry Format 


API req 5D00:20C6 
2E007E3D 2E007E3D C620005D 01000000 <..==..==F .)....> 
00000000 00000000 00000000 7E3D0A00 Goze se teue ee oie aire B=. .> 
00000000 00000001 00000000 00000000 Rie sdnsie sere epesay never: ef 
O0000004C 55534944 4532204D 4F444531 <...LUSIDE2 MODE1> 
20202008 54505349 44453241 20202020 < - TPSIDE2A > 
20202020 20202020 20202020 20202020 < > 
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<=S== 
RU: 


==R=> 
RU: 


API xr 


API req indicates 
API ret indicates 
indicates 
indicates 
indicates 
indicates 
indicates 


<=S== 
==R=> 
# 

TH 
RH 


#:6000 TH: 2DO00101000E 


31001307 
44453120 
4F455420 


BOBODOB1 01008585 
28000902 4D4F4445 
4B4C5553 49444531 


#:4F00 TH:2D000101000E 


31001307 
4D4F4445 
49444532 


et 

67007E3D 
00000000 
00000000 
0000004C 
20202008 
20202020 


BOBODOB1 01018585 
31202020 09030000 
2000 


5D00: 20C6 
67007E3D C620005D 
00000000 00000000 
CB3D0001 00000000 
55534944 4532204D 
54505349 44453241 
20202020 20202020 


RH: 6B8000 

80010602 00000000 
31202020 09030000 
2000084C 55534944 


RH: EB8000 
81010602 00000000 
OQOOOOFOO 00001205 


00000000 20000008 4C555349 
OOOOOFOO 00001204 41505043 
453220 


00000000 20000000 28000902 
41505043 4E455420 4B4C5553 


01000000 <g.==g.==F .)....> 
7E3DOA00 Qe ee wees aed 
00000000 See Ss Fe aes stees > 
4F444531 <...LUSIDE2 MODE1> 
20202020 < - TPSIDE2A > 
20202020 < > 


an issued verb at the given address 

a completed verb at the given address 
a message being sent 

a message being received 
the size in hexidecimal of the RU 
the Transmission Header 

the Request or Response Header 


The second line and succeeding lines describe the RU in 
groups of 8 hexidecimal digits (4 bytes). 

indicates APPC/PC has performed truncation 
according to the TRUNC specification. 
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DISABLE/ENABLE_APPC 


This verb provides a program with the ability to enable 
and disable the operation of APPC/PC. A program can 
use this verb to avoid recursion problems in exit routines 
after it intercepts a call to DOS or BIOS (if those exit 
routines include calls to DOS or BIOS). 


APPC/PC does not end completely when the application 
subsystem specifies the DISABLE option. Instead, the 
adapters continue operating to queue incoming messages 
for APPC/PC. APPC/PC processes these queued messages 
after the program specifies the ENABLE option. 


In addition to the DISABLE/ENABLE_APPC verb, 
APPC/PC can execute the CONVERT, TRACE, 

SET PASSTHROUGH, and PASSTHROUGH verbs when 
it is operating in the disabled state. In normal operation, 
the program should not issue any other APPC/PC verbs. 
If the program issues one of the other APPC/PC verbs, it 
receives an APPC_DISABLED return code. 


Supplied Parameters: 


DISABLE_OR_ENABLE (DISABLE) 
(ENABLE ) 


DISABLE /ENABLE_APPC 


Supplied Parameters: 


DISABLE _OR_ENABLE specifies whether to disable or 
enable APPC/PC operation. The two options for this 
parameter are: 


e DISABLE: Suspends APPC/PC operation. 
e ENABLE: Resumes APPC/PC operation. 
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Chapter 10. Resolving Error 
Conditions 


This chapter describes different kinds of error conditions 
and indicates possible solutions. 


The types of error conditions that can occur during 
APPC/PC operation are: 


e Errors indicated with a return code 
e Errors indicated in a log 
e System deadlocks. 


Note that APPC/PC can detect return code and log errors 
but cannot detect system deadlocks. 


Return Code Error Indications 


When an application subsystem or transaction program 
issues a verb, APPC/PC uses the RETURN_CODE 
parameter to indicate the success or failure of the request. 
The program requesting APPC/PC services by issuing the 
verb must check the value of the return code to determine 
its next action. Appendix C, “Verb Return Codes” 
contains the complete list of return codes that APPC/PC 
can report after it executes (or attempts to execute) each 
verb. This appendix also suggests the appropriate actions 
to correct the problem causing the error. 
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Logged Errors 


During processing, APPC/PC can detect error conditions 
that are not directly associated with verb requests. In 
addition to APPC/PC, a transaction program at either end 
of a conversation can also detect these errors. 


When APPC/PC detects this type of error, it builds a 
SYSLOG control block, and invokes the error exit routine 
that the application subsystem specifies. Use of a log exit 
routine is recommended because APPC/PC itself does not 
display error messages. 


System Deadlocks 


Using Multiple Active Transaction 
Programs 


System deadlocks can occur as a result of one verb 
blocking the completion of another verb, or due to other 
unforeseen conditions. This section describes methods of 
diagnosing and correcting system deadlocks. 


Under a single-tasking operating system such as PC DOS 
on the IBM PC, certain deadlock conditions are possible 
which can be prevented by careful design of the 
application subsystem. 


These deadlocks involve “blocking” verbs that do not 
return control to the transaction program until some form 
of data or indicator has been received from the remote 
partner. The remote partner must issue a verb on the 
conversation before control at the local node can be 
returned. Deadlock occurs when the partner cannot issue 
that verb because it too is issuing a blocking verb on a 
different simultaneous conversation. 
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The potential blocking verbs include most conversation 
verbs. (Any verb that lists INCOMPLETE as a possible 
return code is a potential blocking verb.) 


Such deadlocks are possible only when all nodes involved 
in the simultaneous conversations operate under a 
single-tasking system (which is the case if all nodes are 
IBM PCs), and only if the graph of such nodes forms a 
loop. For example, using parallel sessions between two 
IBM PCs forms a loop between them. 


Such deadlocks are not possible if you support only one 
active transaction program (one TP_ID) at every | 
single-tasking node. In this case no such loop is possible 
because you can allocate a conversation only to a new 
remote transaction program, not to an existing one. 


An example of a situation where two parallel 
conversations can experience a blocking deadlock 
condition is when each of the partner programs waits for 
data after issuing a RECEIVE _AND_ WAIT verb. While 
these transaction programs wait, no other transaction 
program at either node can issue a SEND_DATA to 
satisfy its partner. The figure below illustrates this 
deadlock situation. 


IBM PC 1 IBM PC 2 


Transaction 2B 


RECEIVE AND WAIT 
(suspended) 


Transaction 1B Transaction 2A 


SEND DATA SEND DATA 
(cannot execute, (cannot execute, 
APPC/PC busy) APPC/PC busy) 


If Transaction 1A (in IBM PC 1) is conversing with 
Transaction 2A (in IBM PC 2), and issues a 
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RECEIVE AND _ WAIT on that conversation, IBM PC 1 
waits until data is received to satisfy the 
RECEIVE AND_ WAIT. If Transaction 2B (in IBM PC 2) 
is conversing with Transaction 1B (in IBM PC 1) 
concurrently, and issues a RECEIVE AND WAIT on 
that conversation, then IBM PC 2 also waits to receive 
data. 


Deadlocks are also possible between more than two nodes 
even when only one session and one conversation exists 
between any two nodes. For example, in the figure below, 
if TP 1A in IBM PC 1 ALLOCATKEs conversation 1 to TP 
2A in IBM PC 2, TP 2A ALLOCATEs conversation 2 to 
TP 3A in IBM PC 3, and TP 8A in turn ALLOCATEs 
conversation 3 to TP 1B in IBM PC 1, then TP 1A may 
issue a blocking verb on conversation 1, TP 2A may issue 
one on conversation 2, and TP 3A may issue one on 
conversation 3, each waiting for a verb at the partner 
which will not be issued. The figure below illustrates this 
deadlock situation. 


conversation 2 
IBM PC 2 IBM PC 3 


Use of pacing can also cause a deadlock. A local 
transaction program can be prevented from sending data 
because its remote partner is blocked from issuing a 
receive verb which would clear the session buffers of the 
remote partner. If the session buffers are not cleared, the 
partner cannot transmit the pacing response required 
before the local send can occur. 


If the system appears to be in a deadlock state and if the 
configuration of APPC/PC included the DOS Ctrl-Break 


option, the operator may be able to return to the DOS 
prompt by pressing Ctrl-Break. For a description of 
Ctrl-Break operation, see “Canceling a Transaction” on 
page 2-13 in Chapter 2, “Developing an Application 
Subsystem.” 


Alternately, you can bring down the connection by 
turning off the modem, if there is one. Any existing 
conversations on this line will fail. 


Designing to Avoid System 
Deadlocks 


There are two methods of avoiding deadlocks caused by 
issuing blocking verbs: 


Method 1 (Recommended): Using the INCOMPLETE 
option 


Specify RETURN_CONTROL=INCOMPLETE in the 
ATTACH _PU verb, and expect return codes of 
INCOMPLETE on conversation verbs, as well as on 
TP VALID and TP_ENDED. APPC/PC will return 
control to the application, rather than suspend 
operation even if a verb is unfinished, so that verbs 
that were blocked can now be issued. 


You must issue verbs on all other transaction 
programs, then re-issue the incomplete verb (or verbs, 
if several verbs from different transaction programs 


are incomplete) without alteration. You can, however, 
use the first 12 bytes to keep the incomplete verbs in a 
list. You may have to issue a verb several times before 
it completes. 


If you are using synchronous management of incoming 
ALLOCATEs (queueing them in the LU), and have not 
stopped queueing by issuing a CHANGE_LU verb, you 
must also periodically issue GET_ALLOCATE, 
because a queued ALLOCATE can also cause blocking 
of the partner. 
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In order to manage multiple simultaneous transaction 
programs, the application subsystem can implement 
some form of scheduler to issue verbs from the various 
transaction programs. With Method 1, the scheduler 
must get INCOMPLETE return codes, save the verb 
(or a pointer to it) and periodically re-issue the verb 
until it completés. You should, therefore, use a 
different verb storage buffer, as well as a different data 
buffer, for each transaction program. 


TP_VALID can return INCOMPLETE only if the 
incoming ALLOCATE was rejected with a non-0 sense 
code (in which case the equivalent of SEND_ERROR 
is performed). You do not need to test for 
INCOMPLETE if you accept the incoming 
ALLOCATE. 


TP_ENDED can return INCOMPLETE only if it was 
issued before ending any existing conversations (in 
which case the equivalent of DEALLOCATE TYPE = 
ABEND is performed). You do not need to test for 
INCOMPLETE if all conversations have been 
terminated before you issue TP_ENDED. 


Method 2: Restrictions on your protocol design 


Impose the following restrictions on your transaction 
programs and application subsystem: 


1. Do not use pacing. 


2. Send small amounts of data (using one or more 
consecutive SEND_DATA verbs) at a time. Wait 
for data from the partner that indicates it has 
received what you have sent before sending more. 
The amount that you can send at one time depends 
on the storage that is made available to your node 
and the partner. (For more information, see 
“APPC/PC Workspace Requirements” in the 
APPC/PC Installation and Configuration Guide.) 


3. Do not use conversations with a synchronization 
level of CONFIRM. 
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4. Do not use the following blocking verbs: 


e ALLOCATE or MC_ALLOCATE (TYPE = 
WHEN_SESSION_ALLOCATED) 


e SEND_ERROR or MC_SEND_ERROR 


e RECEIVE_AND_WAIT or 
MC_RECEIVE_AND_WAIT 


e DEALLOCATE(TYPE = ABEND_PROG, 
ABEND_SVC, ABEND_TIMER) 


e MC_DEALLOCATE(TYPE = ABEND) 
e WAIT. 


5. If you use synchronous management of incoming 
ALLOCATHEs, stop queueing (by issuing the 
CHANGE_LU verb) when any transaction program 
is initiated. You can start multiple transaction 
programs by using the asynchronous exit. 


6. Do not issue TP VALID with a non-0 sense code in 
the CREATE_TP structure. Use the asynchronous 
exit if you need to test, and possibly reject, 
incoming ALLOCATEs. 


7. Issue TP_ENDED only after all conversations of 
the transaction program have been deallocated. 


Investigating a Deadlock Situation 


The TRACE verb can provide valuable information for 
debugging many problems, including deadlock situations. 
For a description of the TRACE verb, see “TRACE” on 
page 9-8 in Chapter 9, “Other APPC/PC Services.” You 
can determine the point at which a deadlock occurs by 
enabling tracing. Tracing indicates both the start and 
finish of verb execution. This information can indicate 
which verb was the last one to start before the deadlock 
occurred. You can also use tracing to check the contents 
of the parameter lists for each verb as it executes. 


Appendix A. Verb Operation 
Codes and Formats 


This appendix defines the operation codes for APPC/PC 
verbs and the internal formats for the parameter lists 
passed between a transaction program and APPC/PC. 


APPC/PC to Transaction Program 
Verbs 


APPC/PC performs a FAR CALL to execute verbs that 
send information from APPC/PC to the application 
subsystem (SYSLOG, CREATE_ TP, 
ACCESS_LU_LU_PW). The SS: SP register pair points 
to an 8-byte field on the stack. The 8 bytes consist of: 


e A return address (4 bytes in IBM PC byte order) 
e A verb pointer (4 bytes in IBM PC byte order). 


In many programming languages, this procedure is the 
standard calling convention used when a program passes a 
single parameter (such as a verb pointer) to a subroutine. 
When the routine begins, at least 64 bytes of stack space 
are available on the stack for use by the routine. 
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When the routine is complete and ready to return control 
to APPC/PC, it must remove the verb pointer parameter 
from the stack. In IBM PC Macro Assembler language, 
the return statement would appear as follows: 


create_tp proc far 


ret 4 ;Return to APPC after 
sremoving verb pointer 
create_tp endp 


Transaction Program to APPC/PC 
Verbs 


All verb requests come to APPC/PC through interrupt 
vector X’68’. The transaction program can verify that 
APPC/PC is loaded by checking for the ASCII character 
string ‘APPC/PC’ starting 9 bytes prior to the address 
pointed to by interrupt vector X’68’ (storage location 416). 


Before issuing the interrupt, the transaction program sets 
the AH register as indicated by the record format for each 
verb and points the DS:DX register pair to the location of 
the verb parameter list. 


If APPC/PC receives an invalid AH value from the 
transaction program, it rejects the verb and places a value 
of X’FF’ in the AL register. APPC/PC indicates a valid 
AH value by setting AL to 0. The AH setting for each 
verb appears immediately after the header line for the 
verb record. Following the AH setting for each verb is 
the parameter list. The first parameter you supply on this 
list is the operation code that identifies the verb. 
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Verb Operation Codes 


The following is a list of the verb operation codes and 
their corresponding hexadecimal values. 


Op Code AH Verb Name 
(hex) Value 


0100 2 ALLOCATE or MC_ALLOCATE 

0200 2 (reserved) 

0300 2 CONFIRM or MC_CONFIRM 

0400 2 CONFIRMED or MC_CONFIRMED 

0500 2 DEALLOCATE or MC_DEALLOCATE 

0600 2 FLUSH or MC_FLUSH 

0700 2 GET_ATTRIBUTES or 
MC_GET_ATTRIBUTES 

0800 2 GET TYPE 

0900 2 POST_ON_RECEIPT 

0A00 2 PREPARE TO_RECEIVE or 
MC_PREPARE_TO RECEIVE 

0BO00 2 RECEIVE _AND_WAIT or 

| MC_RECEIVE_AND_ WAIT 

0CO00 2 RECEIVE _IMMEDIATE or 
MC_RECEIVE_IMMEDIATE 

0D00 (reserved) 

OE00 2 REQUEST_TO_ SEND or 
MC_REQUEST_TO_ SEND 

OF00 2 SEND_DATA or MC_SEND_ DATA 

1000 2 SEND_ERROR or 
MC_SEND_ERROR 

1100 - (reserved) 

1200 2 TEST or MC_TEST 

1300 2 WAIT 

1400 - (reserved) 

1500 6 CNOS 

1600 - (reserved) 

1700 - (reserved) 

1800 - (reserved) 

1900 - ACCESS _LU_LU_PW 

1A00 251 CONVERT 

1B00 1 DISPLAY 
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Op Code AH Verb Name 
(hex) Value 


1C00 5 TRANSFER MS DATA 
1D00 - (reserved) 

1E00 - (reserved) 

1F00 - (reserved) 

2000 1 ATTACH PU 
2100 1 ATTACH LU 
2200 1 DETACH _ LU 
2300 - CREATE TP 

2400 3 TP_STARTED 
2500 4 TP ENDED 

2600 - SYSLOG 

2700 1 DETACH _ PU 
2800 3 GET ALLOCATE 
2900 4 TP VALID 

2A00 3 CHANGE LU 
2B00 1 ACTIVATE _DLC 


Verb Record Formats 


The rest of this appendix contains the record formats for 
the APPC/PC verbs. The records appear in alphabetic 
order according to the verb names. 


Each record begins with a header line that specifies the 
AH value. Following the header line, each record 
includes four columns: 


e Disp indicates the displacement of the parameter from 
the beginning of the record. 


e Lng indicates the length of the parameter field in 
bytes. 


e Value indicates any constant values defined for the 
parameter. 


e Field Name indicates the name of the parameter field 


and the names of constant parameter values (indented 
below the name of the constant parameter). 


A-4 


The program using APPC/PC must set all “Reserved” 
parameters to 0. 


Most data fields of the verb are in normal order with the 
high order byte in the lower address. However, for values 
designated by an asterisk (*) in the “Length” column, the 
value is in the reversed-order style of the IBM PC. That 
is, for 2-byte values (such as a length field), the IBM PC 
stores the most significant byte in the right-most byte of 
the field. The decimal value appears within parentheses 
for such a field if it is a non-0 constant. 


Similarly, for 4-byte values (such as an address field), the 
most significant byte is stored in byte 3 (right-most) of the 
field, the next-most significant byte is stored in byte 2 of 
the field, the next in byte 1 of the field, and the 
least-significant byte is stored in byte 0 of the field. 


The IBM PC uses the following ordering conventions for 
bit fields: bit 0 is the left-most bit of a field; bit 7 is the 
right-most bit of a byte; and bit 15 is the right-most bit of 
a half-word. 


All data areas passed to APPC/PC, either for sending or 
receiving data, must fit within a single segment. For 
example, when issuing the RECEIVE_AND_WAIT verb, a 
program provides a 32-bit pointer and a 16-bit maximum 
length value specifying the area into which APPC/PC 
places received data. All bytes in the range delimited by 
these values must have the same segment value. 


For example, a transaction program violates this 
restriction if the data area pointer was segment X’1234’, 
the offset was X’FFF0’ and the length was X’0030’. In this 
case, the sum of the offset and length exceeds X’F FFF’, 
the maximum offset value within a segment. APPC/PC 
provides individual return codes to indicate violations of 
this restriction. 


A double asterisk (**) in the “Value” column indicates 
that APPC/PC uses the field internally. 


APPC/PC operation requires at least 256 bytes of stack 
space. At least 320 bytes must be available if the program 
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specifies tracing. This allocation provides 64 bytes of 
stack space for interrupt processing while using 


APPC/PC. 

Note: 

All numbers in the following formats are decimal unless 
preceded by an X (meaning hexadecimal) or a B (meaning 


bit). In this appendix, the abbreviation CS:IP refers to the 
Code Segment: Instruction Pointer (offset) values. 


ACCESS _LU_LU_PW 


record format 


Disp Lng Value Field Name 

0 12 ee Required APPC/PC area 

12 2* X’1900’ (25) Verb operation code 

14 8 LU_ID 

22 8 LU_NAME 

30 8 PARTNER LU_NAME 

38 17 PARTNER_FULLY_QUALIFIED_LU_NAME 

55 1 PASSWORD_AVAILABLE 
X’00’ NO 
X’01’ YES 

56 8 PASSWORD 


ACTIVATE_DLC 


record format (AH =1) 


Disp Lng Value Field Name 

0 12 *& Required APPC/PC area 
12 2* X’2B00’ (48) Verb operation code 

14 6 6X’00’ Reserved 

20 4 RETURN_CODE 


X’00000000’ OK 

X’00000008’ NO_PU_ATTACHED 
X’00000283’ DLC_FAILURE 
X’00000284’ UNRECOGNIZED_DLC 
X’00000286’ DUPLICATE_DLC 
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Disp Lng Value 


82 


1 


X’F 0010000’ 
X’F0020000’ 
X’F0030000’ 


Field Name 


APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
DLC_NAME 

ITRN 

SDLC 
ADAPTER_NUMBER 


ALLOCATE and MC_ALLOCATE 


record format (AH = 2) 


Disp Lng Value 


0 
12 
14 


15 
20 


22 


26 
34 
38 


39 


12 
gx 
1 


= & 00 


kk 


X’0100’ (1) 


X’00 
X’0l’ 
5X00’ 


X’0000’ 
X’0001’ 
X’0003’ 
X’0014’ 
X’FO0Y’ 
X’F002’ 
X’F003’ 
X’F004’ 


Field Name 


Required APPC/PC area 

Verb operation code 

Verb extension code 
ALLOCATE 
MC_ALLOCATE 

Reserved 

Primary RETURN_CODE 
OK 
PARAMETER CHECK 
ALLOCATION_ERROR 
UNSUCCESSFUL 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
INCOMPLETE 

Secondary RETURN_CODE 
BAD_TP_ID 
ALLOCATION FAILURE _NO_RETRY 
ALLOCATION_FAILURE_RETRY 
DATA AREA ACROSS_ SEGMENT 
BAD_TPN_LEN 
BAD_CONV_TYPE 
BAD_SYNC_LEVEL 
BAD_SECURITY_SELEC 
BAD_RETURN_CONTROL 
TOO_BIG_SEC_TOKENS 
PIP_LEN_INCORRECT 
NO_USE_OF_SNASVCMG 
UNKNOWN_PARTNER_ MODE 

TP_ID 

CONV_ID 

CONVERSATION_TYPE (note 1) 
BASIC_CONVERSATION 
MAPPED_CONVERSATION (user supported) 

SYNC_LEVEL 
NONE 
CONFIRM 
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Disp Lng Value 


40 2 2X00’ 

42 1 
X’00’ 
X’01’ 
X’02’ 

43 8 8X’00’ 

51 8 

59 8 

67 1 

68 64 

132 1 
X’00’ 
X’0l’ 
X’02’ 

13311 11X’00’ 

144 1 

145 10 

155 1 

156 «10 

166 2 

168 4* 


Field Name 


Reserved 
RETURN_CONTROL 
WHEN_SESSION_ALLOCATED 
IMMEDIATE 
WHEN_SESSION_FREE 
Reserved 
PARTNER_LU_NAME 
MODE_NAME 
TP name length 
TP name 
SECURITY 
NONE 
SAME 
PGM 
Reserved 
Password length 
PASSWORD 
User ID length 
USER_ID 
PIP_DATA LENGTH 
(0 if no PIP data) 
PIP_DATA 


Note 1: Reserved if MC ALLOCATE. 


Note 2: Not applicable if MC_ALLOCATE. 


ATTACH _LU 


record format (AH =1) 


Disp Lng Value 


0 12 igs 

12 2* X’2100’ (33) 

14 6 6X00’ 

20 4 
X’00000000’ 
X’00000008’ 
X’00000211’ 
X’00000212’ 
X’00000213’ 
X’00000214’ 
X’00000216’ 
X’00000219’ 
X’0000021A’ 
X’00000284’ 
X’F0010000’ 
X’F 0020000’ 
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Field Name 


Required APPC/PC area 
Verb operation code 
Reserved 
RETURN_CODE 
OK 
NO_PU_ATTACHED 
ALREADY_ACTIVE_LU 
BAD_PART_SESS 
BAD_RU_ SIZES 
BAD_MODE_SESS 
BAD_PACING_CNT 
EXTREME_RUS 
SNASVCMG_1 
UNRECOGNIZED_DLC 
APPC_DISABLED 
APPC_BUSY 


Disp Lng Value 


24 2° 
26 8 
34 8 
42 1 
43 1 
44 4* 
48 4* 
52 4* 
56 4* 
60 1 
61 1 
62 4* 
66 4* 
70 2* 
72+0 2* 
2 Q* 
4 8 
12 1 
bits 0-4 
bit 5 
bit 6 
bit 7 
13 1 
14 2* 
16 8 
24 1 
25 1 
26 16 
42 Q* 
44+0 2* 


X’F0030000’ 
X’4600’ (70) 


X’FFFFFFFY’ 
X’00000000’ 
4X’00’ 


X’FFFFFFFF’ 


4X’00’ 


X’FFFFFFFF’ 
4X’00’ 


Field Name 


APPC_ABENDED 
Offset to partner LU record 

length field 
LU_NAME 
LU_ID 
LU_LOCAL_ADDRESS 
LU_SESSION_LIMIT 
CREATE_TP_EXIT 

(in CS :IP format) 

Reject incoming ALLOCATES 

QUEUE_ALLOCATES (YES) 
Reserved 
SYSTEM_LOG_EXIT 

(in CS :IP format) 

Do not log errors 
Reserved 
MAX_TPS 
QUEUE_DEPTH 
LU_LU_PASSWORD_ EXIT 

(in CS :IP format) 

No password exit 
Reserved 
Total length of partner LU 

records 


(Repeat for each partner LU) 


X’2.A00' (42) 


B’00000’ 


BY’ 
B’1’ 


BO’ 
B’1’ 


B’0’ 
B’Y’ 


X’1000" (16) 


Length of this partner LU 
record (including parameters for 
each mode name defined) 
Offset to start of mode records 
PARTNER _LU_NAME 


PARTNER_LU_SECURITY_CAPABILITIES 


Reserved 

Session level security 

Not supported 

Supported 

Conversation level security 

Not supported 

Supported 

Already verified 

Not supported 

Supported 
PARTNER_LU_SESSION_LIMIT 
PARTNER_LU_MAX | 

MC_SEND_LL 
PARTNER _LU_DLC_NAME 
PARTNER_LU_ADAPTER_ NUMBER 
Length of partner LU adapter 
address 
PARTNER _LU_ADAPTER_ADDRESS 
Total length of all mode 
name records 
Length of this mode name 
record 
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Disp Lng Value Field Name 


(Repeat for each mode) 


2 8 MODE NAME 

10 2* RU_SIZE high bound 

12 2* RU_SIZE low bound 

14 #1 MODE MAX NEGOTIABLE _ 
SESSION_LIMIT 

15 1 PACING_SIZE (for receive) 


ATTACH_PU 


record format (AH=1) 


Disp Lng Value Field Name 

0 12 ee Required APPC/PC area 

12 2* X’2000’ (82) Verb operation code 

14 6 6X’00’ Reserved 

20 4 RETURN_CODE 
X’00000000’ OK 
X’00000201’ ALREADY_ACTIVE_PU 
X’F0010000’ APPC_DISABLED 
X’F0020000’ APPC_BUSY 
X’F0030000’ APPC_ABENDED 

24 2 X’0000’ Reserved 

26 1 VERSION 

27 1 RELEASE 

28 8 NET_NAME 

36 8 PU_NAME 

44 8 8X’00’ Reserved 

52 4* SYSTEM_LOG_EXIT 


(in CS :IP format) 
(X’FFFFFFFF’ = > none) 


56 4 4X’00’ Reserved 

60 1 RETURN_CONTROL 
X’00’ COMPLETE 
X01’ INCOMPLETE 
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CHANGE_LU 


record format (AH = 3) 


Disp Lng 


0 

12 
14 
20 


24 
26 
34 


38 
42 


46 
50 
51 
52 


56 


CNOS 


12 
9* 
6 
4 


4* 


4* 


Value 


** 


X’2A00’ (42) 
6X’00’ 


X’00000000’ 

X’00000003’ 

X’00000230’ 

X’F 0010000’ 

X’F0020000’ 

X’F0030000’ 
2X00’ 


X’FFFFFFFE’ 
X’00000000’ 
4X00’ 


X’FFFFFFFF’ 
4X00’ 


X’00’ 
X01’ 


X’FFFFFFFY’ 
4X’00/ 


Field Name 


Required APPC/PC area 
Verb operation code 
Reserved 
RETURN_CODE 
OK 
BAD_LU_ID 
INVALID_CHANGE 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
Reserved 
LU_ID 
CREATE_TP_EXIT 
(in CS :IP format) 
Reject incoming ALLOCATES 
QUEUE_ALLOCATES (YES) 
Reserved 
SYSTEM_LOG_EXIT 
(in CS :IP format) 
Do not log errors 
Reserved. 
MAX_TPS 
QUEUE_ALLOCATES 
STOP 
RESUME 
LU_LU_PASSWORD_ EXIT 
No password exit 
Reserved 


record format (AH =6) 


Disp Lng Value 


0 

12 
14 
20 


12 
Q* 
6 
2 


kk 


X’1500’ (21) 


6X’00’ 


X’0000’ 
X’0001’ 
X’0002’ 


Field Name 


Required APPC/PC area 

Verb operation code 

Reserved 

Primary RETURN_CODE 
OK 
PARAMETER_CHECK 
STATE CHECK 


A-11 


Disp Lng Value 


22 4 


26 
34 
42 
50 


e% oO © 0O 


58 
bits 0-5 
bit 6 


_ 


bit 7 


59 
60 
61 
62 
63 
64 
bits 0-4 
bit 5 


a eer oar 


bit 6 
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X’0003’ 
X’0018’ 
X’F001’ 
X’F002’ 
X’F 003’ 


X’00000000’ 
X’00000001’ 
X’00000003’ 
X’00000004’ 
X’00000005’ 
X’00000151’ 
X’00000153’ 
X’00000154’ 
X’00000155’ 
X’00000156’ 


X’00000156’ 
X’00000157’ 
X’00000157’ 
X’00000159” 
X’0000015A’ 
X’0000015B’ 
X’0000015C’ 
X’0000015D’ 
X’0000015E’ 
X’0000015F” 


8X’20’ 


B’000000’ 


BY” 
B’1’ 


BY’ 
BY’ 


X’00’ 
B’00000’ 
B’0’ 
BY’ 
B’0’ 
B’1’ 


Field Name 


ALLOCATION_ERROR 
CNOS_PARTNER_LU_REJECT 
APPC_ DISABLED 
APPC_BUSY 
APPC_ABENDED 

Secondary RETURN_CODE 
CNOS_ACCEPTED 
CNOS_NEGOTIATED 
BAD_LU_ID 
ALLOCATION_FAILURE_NO_RETRY 
ALLOCATION_FAILURE_RETRY 
CANT_RAISE_LIMITS 
ALL_MODE_MUST_RESET 
BAD_SNASVCMG_LIMITS 
MINS_GT_TOTAL 
MODE_CLOSED 
(primary RETURN_CODE - X’0001’) 
CNOS_MODE_ CLOSED 
(primary RETURN_CODE - X’0018’) 
BAD_MODENAME 
(primary RETURN_CODE - X’0001’) 
CNOS_BAD MODENAME 
(primary RETURN_CODE - X’0018’) 
RESET_SNA_DRAINS 
SINGLE_NOT_SRC_RESP 
BAD_PARTNER_ LU 
EXCEEDS MAX ALLOWED 
CHANGE_SRC_DRAINS 
LU_DETACHED 
CNOS_COMMAND_RACE_REJECT 

LU_ID 

Reserved 

PARTNER_LU_NAME 

MODE_NAME 

Gf MODE_NAME_SELECT=ONE) 


Reserved 
SET_NEGOTIABLE 
Do not set negotiable values 
Set negotiable values 
MODE_NAME_SELECT 
ONE 
ALL 
PARTNER _LU_MODE_SESSION_LIMIT 
MIN_CONWINNERS_SOURCE 
MIN_CONWINNERS_ TARGET 
AUTO_ACTIVATE 
Reserved 
Termination settings 
Reserved 
RESPONSIBLE 
SOURCE (local) 
TARGET (partner) 
DRAIN_SOURCE 
NO 
YES 


Disp Lng Value Field Name 


bit 7 DRAIN _ TARGET 
BY’ NO 
B’1’ YES 


CONFIRM or MC_CONFIRM 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 = Required APPC/PC area 

12 2* X’0300’ (3) Verb operation code 

14 1 Verb extension code 
X’00’ CONFIRM 
X’01’ MC_CONFIRM 

15 5 5X’00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER_CHECK 
X’0002’ STATE_CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 2) 
X’0006’ DEALLOCATE_ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_SVC (note 1) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 1) 
X’000K” PROG_ERROR_PURGING 
X’000F” CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0013’ SVC_ERROR_ PURGING (note 1) 
X’0019’ CONVERSATION_TYPE_MIXED 
X’FOO’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 

22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000031’ CONFIRM_ON_SYNC_NONE 
X’00000032’ CONFIRM_BAD_STATE 
X’00000033’ CONFIRM_NOT_LL_BDY 

26 8 TP_ID 

34 4 CONV_ID 

38 1 REQUEST_TO_SEND_ RECEIVED 
X’00’ NO 
X’01’ YES 


Note 1: Not applicable if MC_CONFIRM. 
Note 2: Not applicable if CONFIRM. 


For descriptions of the ALLOCATION ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 
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Verbs” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” . 


CONFIRMED or MC_CONFIRMED 


record format (AH = 2) 


Disp Lng Value Field Name 


0 12 id Required APPC/PC area 
12 2* X’0400’ (4) Verb operation code 
14 1 Verb extension code 
X’00’ CONFIRMED 
X01’ MC_CONFIRMED 
15 5 5X’00’ Reserved 
20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER _CHECK 
X’0002’ STATE CHECK 
X‘0019’ CONVERSATION_TYPE_ MIXED 
X’FO01’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000041’ CONFIRMED_BAD_STATE 
26 8 TP_ID 
34 4 CONV_ID 


CONVERT 


record format (AH = 251) 


Disp Lng Value 


Field Name 


0 12 ee Required APPC/PC area 

12 2* X’1A00’(26) Verb operation code 

14 6 6X00’ Reserved 

20 4 RETURN_CODE 
X’00000000° OK 
X’00000401’ INVALID DIRECTION 
X’00000402’ INVALID_TYPE 
X’00000403’ SEGMENT OVERLAP 
X’00000404’ INVALID_FIRST_CHARACTER 
X’00000405’ TABLE_ERROR 


A-14 


Disp Lng Value Field Name 


X’00000406’ CONVERSION_ERROR 
X’F 0030000’ APPC_ABENDED 
24 1 DIRECTION 
X’00’ ASCH_TO_EBCDIC 
X’01’ EBCDIC_TO_ASCII 
25 1 CHARACTER_SET 
X’00’ AE 
X01’ A 
X’02’ G 
26 2* LENGTH 
28 4* SOURCE 
32 4* TARGET 


record format 


Disp Lng Value Field Name 

0 12 ** Required APPC/PC area 

12 2* X’2300’ (35) Verb operation code 

14 6 6X’00’ Reserved 

20 4 SENSE_CODE 
X’00000000’ OK 
X’080F 6051’ SECURITY_NOT_VALID 
X’084B6031’ TP_NOT_AVAIL_RETRY 
X’084C0000’ TP_NOT_AVAIL_NO_RETRY 
X’10086021’ TP_NAME_NOT_RECOGNIZED 
X’10086034’ CONVERSATION_TYPE_MISMATCH 
X’10086041’ SYNC_LEVEL_NOT_SUPPORTED 

24 8 TP_ID 

32 8 LU_ID 

40 4 CONV_ID 

44 1 TYPE 
X’00’ BASIC_CONVERSATION 
X’01’ MAPPED CONVERSATION 

45 1 SYNC_LEVEL 
X’00’ NONE 
X’01’ CONFIRM 

46 Reserved 

47 Transaction program name length 

48 TPN 

112 6X’00’ Reserved 


¥ 


Length of ERROR_LOG_DATA to return 
Pointer to ERROR _ LOG_DATA to return 
PARTNER_LU_NAME 
Length of fully qualified partner LU name 
PARTNER_FULLY_QUALIFIED_LU_NAME 
MODE_NAME 

12X’00’ Reserved 
Length of password 


+ 


_ 
to 
nN 

Hh ogroanaPer 
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Disp Lng Value Field Name 


171 10 PASSWORD 
181 1 Length of user ID 
182 10 USER_ID 
192 1 ALREADY_VERIFIED 
X’00’ NO - Verification should 
be performed 
X01’ YES 


DEALLOCATE or 
MC_DEALLOCATE 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 ** Required APPC/PC area 

12 2* X’0500 (5) Verb operation code 

14 1 Verb extension code 
X’00’ DEALLOCATE 
X01’ MC_DEALLOCATE 

15 5 5X’00 Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER CHECK 
X’0002’ STATE CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 2) 
X’0006’ DEALLOCATE_ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_ SVC (note 1) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 1) 
X’000K’ PROG_ERROR_PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0013’ SVC_ERROR_PURGING (note 1) 
X’0019’ CONVERSATION_TYPE MIXED 
X’FOOI’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 

22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000006’ DATA_AREA_ ACROSS_SEGMENT (note 1) 
X’00000051’ DEALLOC_BAD_ TYPE 
X’00000052’ DEALLOC_FLUSH_BAD_ STATE 
X’00000053’ DEALLOC_CONFIRM_BAD_ STATE 
X’00000055’ DEALLOC_NOT_LL_BDY (note 1) 
X’00000057’ LOG_LL_WRONG (note 1) 

26 8 TP_ID 

34 4 CONV_ID 
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Disp Lng Value 


38 
39 


1 X’00’ 

1 
X’00’ 
X01’ 
X’02’ 
X’03’ 
X04’ 
X’05’ 

2 ‘* 

4* 


Note 1: Not applicable if MC_DEALLOCATE. 


Field Name 


Reserved 
TYPE 
SYNC_LEVEL 
FLUSH 
ABEND_PROG (note 1) 
ABEND_SVC (note 1) 
ABEND_ TIMER (note 1) 
ABEND (note 4) 
Length of error log data (note 3) 
Address of error log data (note 3) 


Note 2: Not applicable if DEALLOCATE. 


Note 3: Reserved if MC_ DEALLOCATE. 


Note 4: Reserved if DEALLOCATE. 


For descriptions of the ALLOCATION ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 


Verbs” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” 


DETACH_LU 


record format (AH = 1) 


Disp Lng Value 


0 


24 
32 


1 2 wk 

2* X’2200’ (34) 

6 6X’00’ 

4 
X’00000000’ 
X’00000003’ 
X’00000223’ 
X’F0010000’ 
X’F0020000’ 
X’F0030000’ 


4 OO 


X’00’ 


Field Name 


Required APPC/PC area 
Verb operation code 
Reserved 
RETURN_CODE 
OK 
BAD_LU_ID 
SSCP_CONNECTED_LU 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
LU_ID 


Reserved 
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DETACH _ PU 


record format (AH=1) 


Disp Lng Value Field Name 

0 12 at Required APPC/PC area 

12 2* X’2700’ (39) Verb operation code 

14 6 6X’00’ Reserved 

20 4 RETURN_CODE 
X’00000000’ OK 
X’00000008’ NO_PU_ATTACHED 
X’00000272 ADAPTER_CLOSE_ FAILURE 
X’F0010000’ APPC_ DISABLED 

24 1 TYPE 
X’00’ HARD 
X01’ SOFT 


DISABLE/ENABLE_APPC 


record format (AH = 250) 


This verb passes all parameters in registers; no control structure 
is used. 


e Disable APPC/PC: AL=1 (note 1) 
e Enable APPC/PC: AL=0 (note 1) 


Note 1: APPC/PC examines only the last bit of the AL 
register. 


DISPLAY 


record format (AH =1) 


Disp Lng Value Field Name 

0 12 das Required APPC/PC area 
12 2* X’1B00’ (27) Verb operation code 

14 6 6X00’ Reserved 

20 4 RETURN_CODE 
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Disp Lng Value Field Name 


X’00000000’ OK 
X’00000003’ BAD_LU_ID 
X’000001B1’ BAD PART LUNAME 
X’000001B2’ BAD_MODENAME 
X’F0010000’ APPC_DISABLED 
X’F0020000’ APPC_BUSY 
X’F0030000' APPC_ABENDED 
X’0000’ Reserved 
LU_ID 
PARTNER LU NAME 
MODE _ NAME 
LU_SESSION_LIMIT 
PARTNER _LU_SESSION_LIMIT 
MODE_MAX_NEGOTIABLE_SESSION_LIMIT 
CURRENT_SESSION_LIMIT 
MIN_NEGOTIATED_WINNER_ LIMIT 
MIN NEGOTIATED _LOSER_ LIMIT 
ACTIVE_SESSION_COUNT 
ACTIVE. CONWINNER_.SESSION_ COUNT 
ACTIVE _CONLOSER_SESSION COUNT 
59 SESSION_ TERMINATION COUNT 
60 Termination settings 
bits 0-5 B’000000’ Reserved 
bit 6 SESSION _ TERMINATION _ 
SOURCE_DRAIN 
B’0’ NO 
BY’ YES 
bit 7 SESSION_ TERMINATION _ 
TARGET_DRAIN 
BY’ NO 
B’1’ YES 


FLUSH or MC_FLUSH 


24 
26 
34 
42 
50 
51 
52 
53 
54 
55 
56 
57 
58 


bk ed et et ed et et et et Et 00 OD 00 DOD 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 fatal Required APPC/PC area 

12 2° X’0600’ (6) Verb operation code 

14 1 Verb extension code 
X’00’ FLUSH 
X’01’ MC_FLUSH 

15 5 5X’00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER CHECK 
X’0002’ STATE_CHECK 
X’0019 CONVERSATION TYPE MIXED 
X’FO01’ APPC_DISABLED 
X’ F002’ APPC_BUSY 
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Disp Lng Value 


22 4 
26 8 
34 4 


X’F003’ 


X’00000001’ 
X’00000002’ 
X’00000061’ 


Field Name 


APPC_ABENDED 

Secondary RETURN_CODE 
BAD_TP_ID 
BAD_CONV_ID 
FLUSH_NOT_SEND_STATE 

TP_ID 

CONV_ID 


GET_ALLOCATE 


record format (AH = 3) 


Disp Lng Value 


0 12 
12 2* 
14 6 
20 4 
24 2 
26 8 
34 1 
35 4* 


GET 


ek 


X’2800’ (40) 
6X’00’ 


X’00000000’ 
X’000000037 
X’00000281’ 
X’00000282’ 
X’F 0010000’ 
X’F 0020000’ 
X’F0030000’ 
2X700’ 


X’00’ 
X01’ 


Field Name 


Required APPC/PC area 
Verb operation code 
Reserved 
RETURN_CODE 
OK 
BAD_LU_ID 
GET_ALLOC_BAD_ TYPE 
UNSUCCESSFUL 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
Reserved 
LU_ID 
TYPE 
DEQUEUE 
TEST 
Pointer to CREATE_ TP record 


_ATTRIBUTES or 
MC_GET_ATTRIBUTES 


record format (AH = 2) 


Disp Lng Value 


0 12 
12 2* 
14 1 
15 5 
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Rk 


X’0700’ (7) 


X’00’ 
X01’ 


5X’00’ 


Field Name 


Required APPC/PC area 

Verb operation code 

Verb extension code 
GET_ATTRIBUTES 
MC_GET_ATTRIBUTES 

Reserved 


Disp Lng Value Field Name 


20 


2 


1 + 00 m OO 


Primary RETURN_CODE 


X’0000’ OK 
X’0001’ PARAMETER CHECK 
X’0019’ CONVERSATION_TYPE_ MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
Secondary RETURN_CODE 
X’00000001’ BAD_TP_ ID 
X’00000002’ BAD _CONV_ID 
TP_ID 
CONV_ID 
LU_ID 
X’00’ Reserved 
SYNC_LEVEL 
X’00’ NONE 
X’01’ CONFIRM 


MODE_NAME 

OWN_NET_ NAME 

OWN_LU_NAME 

PARTNER_LU_NAME 

Length of PARTNER_FULLY_ 
QUALIFIED_LU_NAME 

PARTNER _FULLY_QUALIFIED _ 
LU_NAME 

X’00’ Reserved 
Length of USER_ID 
USER_ID 


_TYPE 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 x Required APPC/PC area 

12 2* X’0800’ (8) Verb operation code 

14 6 6X’00’ Reserved 

20 2 Primary RETURN_CODE 
xX’ y OK 
X’0001’ PARAMETER CHECK 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 

22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 

26 8 TP_ID 

34 4 CONV_ID 

38 1 TYPE 
X’00’ BASIC_CONVERSATION 
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Disp Lng Value Field Name 
X’01’ MAPPED_CONVERSATION 


PASSTHROUGH 


record format (AH =7) 


This verb must be formatted according to the specifications of the 
application subsystem. 


POST_ON_RECEIPT 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 _ Required APPC/PC area 

12 2* X’0900’ (9) Verb operation code 

14 6 6X’00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER_CHECK 
X’0002’ STATE_CHECK 
X’0019’ CONVERSATION_TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 

22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000091’ INVALID_LENGTH 
X’00000092’ P_ON_R_NOT_RCV_STATE 
X’00000093’ P_ON_R_BAD_ FILL 

26 8 TP_ID 

34 4 CONV_ID 

38 2* MAX LENGTH 

40 1 FILL 
X’00’ BUFFER 
X’01’ LL 
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PREPARE TO_RECEIVE and 
MC _ PREPARE TO_RECEIVE 


record format (AH = 2) 


Disp Lng Value Field Name 
0 12 ae Required APPC/PC area 
12 2* X’0A00’ (10) Verb operation code 
14 1 Verb extension code 
X’00’ PREPARE _TO_RECEIVE 
X’01’ MC_PREPARE TO RECEIVE 
15 5 5X’00’ Reserved 
20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER _ CHECK 
X’0002’ STATE CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 2) 
X’0006’ DEALLOCATE ABEND _ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_SVC (note 1) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 1) 
X’000E’ PROG_ERROR_PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0013’ SVC_ERROR_PURGING (note 1) 
X’0019’ CONVERSATION_TYPE_MIXED 
X’FO0l’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’000000A1’ P_TO_ R INVALID TYPE 
X’000000A 2’ UNFINISHED_LL (note 1) 
X’000000A3’ P_TO_R_ NOT_SEND_STATE 
26 8 TP_ID 
34 4 CONV_ID 
38 1 TYPE 
X’00’ SYNC_LEVEL 
X’01’ FLUSH 
39 1 LOCKS 
X’00’ SHORT 
X’01’ LONG 


Note 1: Not applicable if MC_PREPARE TO RECEIVE. 


Note 2: Not applicable if PREPARE_TO_ RECEIVE. 


For descriptions of the ALLOCATION_ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 
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Verbs” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” 


RECEIVE_AND_WAIT and 
MC_RECEIVE_ AND WAIT 


record format (AH = 2) 


Disp Lng Value Field Name 
0 12 isi Required APPC/PC area 
12 2* X’0B00’ (11) Verb operation code 
14 1 Verb extension code 
X’00’ RECEIVE_AND_ WAIT 
X’01’ MC_RECEIVE_AND_ WAIT 
15 5 5X’00’ Reserved 
20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER CHECK 
X’0002’ STATE_CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 3) 
X’0006’ DEALLOCATE_ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_ SVC (note 1) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 1) 
X’0009’ DEALLOCATE_NORMAL 
X’000C’ PROG_ERROR_NO_TRUNC 
X’000D’ PROG_ERROR_TRUNC (note 1) 
X’000E’ PROG_ERROR_PURGING 
X’000F” CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0011’ SVC_ERROR_ NO_TRUNC (note 1) 
X’0012’ SVC_ERROR_TRUNC (note 1) 
X’0013’ SVC_ERROR_ PURGING (note 1) 
X’0019’ CONVERSATION_TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000006’ DATA_AREA_ACROSS_ SEGMENT 
X’000000BI’ RCV_AND_WAIT_BAD_STATE 
X’000000B2’ RCV_AND_ WAIT _NOT_LL_BDY (note 1 ) 
X’000000B5’ RCV_AND_ WAIT_BAD_ FILL (note 1) 
26 8 TP_ID 
34 4 CONV_ID 
38 1 WHAT_RECEIVED 
X’00’ DATA (note 1) 
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Disp Lng Value Field Name 


X’01’ DATA_COMPLETE 
X’02’ DATA INCOMPLETE 
X’03’ CONFIRM 
X’04’ CONFIRM_SEND 
X’05’ CONFIRM_DEALLOCATE 
X’06’ SEND 
39 1 FILL (note 2) 
X’00’ BUFFER 
X’0l’ LL 
40 1 REQUEST_TO_SEND_ RECEIVED 
X’00’ NO 
X’01’ YES 
41 Q* MAX LENGTH 
43 2* DATA _ LENGTH 
45 4* DATA _ PTR 


Note 1: Not applicable if MC_ RECEIVE AND WAIT. 

Note 2: Reserved if MC_ RECEIVE AND WAIT. 

Note 3: Not applicable if RECEIVE _AND_ WAIT. 
For descriptions of the ALLOCATION ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 


Verbs” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” 


RECEIVE IMMEDIATE and 
MC_RECEIVE_ IMMEDIATE 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 ee Required APPC/PC area 

12 2* X’0C00’ (12) Verb operation code 

14 1 Verb extension code 
X’00’ RECEIVE_IMMEDIATE 
X’01’ MC_RECEIVE_IMMEDIATE 

15 5 5X’00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER_CHECK 
X’0002’ STATE _ CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 3) 
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Disp Lng Value Field Name 


X’0006’ DEALLOCATE _ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ ABEND_SVC (note 1) 
X’0008’ DEALLOCATE ABEND_ TIMER (note 1) 
X’0009’ DEALLOCATE_NORMAL 
X’000C’ PROG_ERROR_NO_TRUNC 
X’000D’ PROG_ERROR_TRUNC (note 1) 
X’000E’ PROG_ERROR_PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0011’ SVC_ERROR_NO_TRUNC (note 1) 
X’0012’ SVC_ERROR_TRUNC (note 1) 
X’0013’ SVC_ERROR_PURGING (note 1) 
X’0014’ UNSUCCESSFUL 
X’0019’ CONVERSATION_TYPE_ MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD _TP_ID 
X’00000002’ BAD _CONV_ID 
X’00000006’ DATA_AREA ACROSS_SEGMENT 
X’000000C1’ RCV_IMMD_NOT_RCV_STATE 
X’000000C4’ RCV_IMMD_BAD_FILL (note 1) 
26 8 TP_ID 
34 4 CONV_ID 
38 1 WHAT_RECEIVED 
X’00’ DATA (note 1) 
X’01’ DATA_COMPLETE 
X’02’ DATA_INCOMPLETE 
X’03’ CONFIRM 
X’04’ CONFIRM_SEND 
X’05’ CONFIRM_DEALLOCATE 
X’06’ SEND 
39 1 FILL (note 2) 
X’00’ BUFFER 
X01’ LL 
40 1 REQUEST_TO_SEND_RECEIVED 
X’00’ NO 
X’01’ YES 
4l 2* MAX LENGTH 
48 2* DATA _LENGTH 
45 4* DATA PTR 


Note 1: Not applicable if MC_RECEIVE IMMEDIATE. 
Note 2: Reserved if MC_RECEIVE_IMMEDIATE. 
Note 3: Not applicable if RECEIVE_ IMMEDIATE. 

For descriptions of the ALLOCATION_ERROR secondary return 


codes, see Chapter 6, “Using Transaction Mapped Conversation 


Verbs” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” 
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REQUEST_TO_SEND and 
MC_REQUEST_TO_SEND 


record format (AH = 2) 


Disp Lng Value Field Name 
0 12 we Required APPC/PC area 
12 2* X’0E00’ (14) Verb operation code 
14 1 Verb extension code 
X’00’ REQUEST_TO_ SEND 
X’01’ MC_REQUEST_TO_ SEND 
15 5 5X00’ Reserved 
20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER _ CHECK 
X’0002’ STATE_CHECK 
Xx’001Y CONVERSATION_TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F 003’ APPC_ABENDED 
X’F004’ INCOMPLETE 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID | 
X’00000002’ BAD_CONV_ID 
X’000000E1’ R_T_S_NOT_RCV_STATE 
26 8 TP_ID 
34 4 CONV_ID 


SEND_DATA or MC_SEND_DATA 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 +e Required APPC/PC area 

12 2* X’OF00’ (15) Verb operation code 

14 1 Verb extension code 
X’00’ SEND_DATA 
X’01’ MC_SEND_DATA 

15 5 5X’00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER_CHECK 
X’0002’ STATE CHECK 
X’0003’ ALLOCATION_ERROR 
X’0005’ DEALLOCATE_ABEND (note 2) 
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Disp Lng Value Field Name 


X’0006’ DEALLOCATE_ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_ SVC (note 1) 
X’0008” DEALLOCATE_ABEND_ TIMER (note 1) 
X’000K’ PROG_ERROR_ PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0013’ SVC_ERROR_PURGING (note 1) 
X’0019’ CONVERSATION TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 
22 4 Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD _CONV_ID 
X’000000086’ DATA AREA ACROSS SEGMENT 
X’000000F 1’ BAD_LL (note 1) 
X’000000F 2’ SEND DATA NOT: SEND_STATE 
26 8 TP_ID 
34 4 CONV_ID 
38 1 REQUEST TO SEND RECEIVED 
X’00’ NO 
X01’ YES 
39 1 X’00’ Reserved 
40 Q* DATA_LENGTH 
42 4* DATA_PTR 


Note 1: Not applicable if MC_SEND_ DATA. 
Note 2: Not applicable if SEND_DATA. 


SEND_ERROR or 
MC_SEND_ERROR 


record format (AH = 2) 


Disp Lng Value Field Name 
0 12 +e Required APPC/PC area 
12 2* X’1000’ (16) Verb operation code 
14 1 Verb extension code 
X’00’ SEND_ERROR 
X’01’ MC_SEND_ERROR 
15 5 5X’00’ Reserved 
20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER CHECK 
X’0003’ ALLOCATION_ERROR 
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Disp Lng Value Field Name 


22 


34 
38 


40 
46 


— m 00 


4 
Q* 
4* 


X’0005’ DEALLOCATE_ABEND (note 3) 
X’0006’ DEALLOCATE_ABEND_ PROG (note 2) 
X’0007’ DEALLOCATE_ABEND_SVC (note 2) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 2) 
X’0009’ DEALLOCATE_NORMAL 
X’000E’ PROG_ERROR_PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE_NO_RETRY 
X’0013’ SVC_ERROR_ PURGING (note 2) 
X’0019’ CONVERSATION_TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 

Secondary RETURN_CODE 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD _CONV_ID 
X’00000006’’ DATA AREA ACROSS SEGMENT 

(note 2) 

X’00000102’ LOG_LL_WRONG (note 2) 
X’00000103’ BAD_TYPE (note 2) 

TP_ID 

CONV_ID 

REQUEST_TO SEND RECEIVED 
X’00’ NO 
X01’ YES 

TYPE (note 1) 
X’00’ PROG 
X’01’ SVC 
4X00’ Reserved 


LOG_DATA_LENGTH (note 1) 
LOG_DATA (note 1) 


Note 1: Reserved if MC_SEND_ERROR. 
Note 2: Not applicable if MC_SEND_ ERROR. 
Note 3: Not applicable if SEND_ERROR. 


For descriptions of the ALLOCATION ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 
Verbs” or Chapter 7, “Using Transaction Basic Conversation 


Verbs.” 
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SET PASSTHROUGH 


format (AH = 255) 


This verb passes all parameters in registers; APPC/PC does not 
require a control structure block. 


DS:DX contains the passthrough exit address. 


SYSLOG 


record format 


Disp Lng Value Field Name 
0 12 ie Required APPC/PC area 
12 2* X’2600’ (38) Verb operation code 
14 10 10X’00’ Reserved 
24 2 TYPE See 
Appendix D, “SYSLOG Type Codes” 
26 4 SUBTYPE See 
Appendix D, “SYSLOG Type Codes” 
30 4* Pointer to ADDITIONAL_INFO 
34 4 CONV_ID (0 if unknown) 
38 8 TP_ID (0 if unknown) 
46 8 PU_OR_LU_NAME (0 if unknown) 
54 2* DATA_LENGTH 
56 4* DATA_ADDRESS 
60 1 X’00’ Reserved 


TEST or MC_TEST 


record format (AH = 2) 


Disp Lng Value Field Name 
0 12 bei Required APPC/PC area 
12 2* X’1200’ (18) Verb operation code 
14 1 Verb extension code 
X’00’ TEST 
. X’01’ MC_TEST 
15 5 5X’00’ Reserved 
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Disp Lng Value Field Name 


20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER_CHECK 
X’0002’ STATE_CHECK (note 1) 
X’0003’ ALLOCATION_ERROR (note 1) 
X’0006’ DEALLOCATE_ABEND_ PROG (note 1) 
X’0007’ DEALLOCATE_ABEND_ SVC (note 1) 
X’0008’ DEALLOCATE_ABEND_ TIMER (note 1) 
X’0009’ DEALLOCATE_NORMAL (note 1) 
X’000A’ DATA_POSTING_BLOCKED (note 1) 
X’000B’ POSTING_NOT_ACTIVE 
X’000C’ PROG_ERROR_NO_TRUNC (note 1) 
X’000D’ PROG_ERROR_TRUNC (note 1) 
X’000E’ PROG_ERROR_PURGING (note 1) 
X’000F’ CONV_FAILURE_RETRY (note 1) 
X’0010’ CONV_FAILURE_NO_RETRY (note 1) 
X’0011’ SVC_ERROR_ NO_TRUNC (note 1) 
X’0012’ SVC_ERROR_TRUNC (note 1) 
X’0013’ SVC_ERROR_PURGING (note 1) 
X’0014’ UNSUCCESSFUL 
X’0019’ CONVERSATION_TYPE_MIXED 
X’F001’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F003’ APPC_ABENDED 
X’F004’ INCOMPLETE 

22 4 Secondary RETURN_CODE 
X’00000000’ POSTED_DATA (note 1) 
X’00000001’ POSTED_NOT_DATA 

(primary RETURN_CODE - X’0000’) 
X’00000001’ BAD_TP_ID 
(primary RETURN_CODE - X’0001’) 

X’00000002’ BAD_CONV_ID 
X’00000121’ TEST_INVALID_TYPE 
X’00000122’ NOT_RCV_STATE (note 1) 

26 8 TP_ID 

34 4 CONV_ID 

38 1 TEST (note 2) 
X’00’ POSTED 
X’01’ REQUEST_TO_ SEND _ RECEIVED 


Note 1: Not applicable if MC_ TEST. 
Note 2: Reserved if MC_TEST. 


For descriptions of the ALLOCATION ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 
Verbs” or Chapter 7, “Using Transaction Basic Conversation 


Verbs.” 
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TP_ENDED 


record format (AH = 4) 


Disp Lng Value 


0 12 beled 

12 Aad X’2500’ (37) 

14 6 6X‘00’ 

20 4 
X’00000000’ 
X’00000001’ 
X’F0010000’ 
X’F0020000’ 
X’F0030000’ 
X’F0040000’ 

24 2 2X’00’ 

26 8 


Field Name 


Required APPC/PC area 

Verb operation code 

Reserved. 

RETURN_CODE 
OK 
BAD_TP_ID 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 
INCOMPLETE 

Reserved 

TP_ID 


TP_STARTED 


record format (AH = 3) 


Disp Lng Value 


0 12 wi 

12 2* X’2400’ (36) 

14 6 6X’00’ 

20 4 
X’00000000’ 
X’00000003’ 
X’00000243’ 
X’F0010000’ 
X’F0020000’ 
X’F0030000’ 

24 2 2X’00’ 

26 8 

34 8 
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Field Name 


Required APPC/PC area 

Verb operation code 

Reserved 

RETURN_CODE 
OK 
BAD_LU_ID 
TOO_MANY_TPS 
APPC_DISABLED 
APPC_BUSY 
APPC_ABENDED 

Reserved 

LU_ID 

TP_ID 


TP_VALID 


record format (AH = 4) 


Disp Lng Value Field Name 

0 12 =e Required APPC/PC area 

12 2* X’2900’ (41) Verb operation code 

14 6 6X00’ Reserved 

20 4 RETURN_CODE 
X’00000000’ OK 
X’00000001’ BAD_TP_ID 
X’00000002’ BAD_CONV_ID 
X’00000110’ BAD_STATE 
X’F0010000’ APPC_DISABLED 
X’F0020000’ APPC_BUSY 
X’F0030000’ APPC_ABENDED 
X’F0040000’ INCOMPLETE 

24 2 2X00’ Reserved 

26 8 TP_ID 

34 4* CREATE_TP_ PTR 


TRACE 


formats 


This verb passes all parameters in registers; APPC/PC does not 
require a control structure block. 


TRACE MESSAGES (AH = 252) 
— AL=0: Trace OFF (disable message tracing) 
— AL=1: Trace ON (enable message tracing) 


DX=n: Number of bytes at which to truncate RU 
DX=0: Indicates no truncation 


TRACE_API (AH = 253) 

— AL=1: Trace ON (enable API verb trace) 
— AL=0: Trace OFF (disable API verb trace). 
TRACE_DESTINATION (AH = 254) 
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Combinations of the following values cause APPC/PC to 
direct the trace statistics to multiple destinations. For 
example, AL=6 directs the trace output to the display of the 
IBM PC and to a file in the current directory. 
— AL=1: STORAGE 

DS:DX = user-provided address of TRACE STATS 
— AL=2: DISPLAY 
— AL=4: FILE 


OUTPUT.PC = file containing the trace 
DS:DX = user-provided address of TRACE_STATS 


—- AL=8: PRINTER 


TRACE _ STATS formats 


Record format for TRACE STATS, pointed to by DS :DX. 


Disp Lng Description 


0 


12 


4* Start address of 
storage buffer (needed 
for storage trace only) 


2* Maximum number of records 
to retain (file or buffer 
will wrap after this many 
80-byte records) 


2 Current record number 
(must be initialized to 0) 


4 Number of records written 
(must be initialized to 0) 


4 Reserved 


Note: The TRACE STATS record must remain at the specified 
address while tracing is active. When tracing to STORAGE or 
FILE, APPC/PC updates the record number (displacement 6) and 
number of records written (displacement 8) each time it makes a 
trace entry. 
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TRANSFER_MS DATA 


record format (AH =5) 


Disp Lng Value Field Name 
0 12 ied Required APPC/PC area 
12 2* X’1C00’ (28) Verb operation code 
14 1 DATA_TYPE 
X’00’ USER_DEFINED 
X’01’ NMVT 
X’02’ ALERT_SUBVECTORS 
X’03’ PDSTATS SUBVECTORS 
15 5 5X’00’ Reserved. 
20 4 RETURN_CODE 
X’00000000’ OK 
X’00000301’ SSCP_PU_SESSION_NOT_ACTIVE 
X’00000302’ DATA_EXCEEDS_RU_ SIZE 


X’F0010000 APPC_DISABLED 
X’F0020000’ APPC_BUSY 


X’F0030000’ APPC_ABENDED 
24 12 12X’00’ Reserved 
36 1 Verb options 
bit 0 CORRELATOR_SUBVECTOR 
B’0’ ADD 
BI’ NO_ADD 
bit 1 PRODUCT_SET_ID_ SUBVECTOR 
BO’ ADD 
BY’ NO_ADD 
bit 2 SYSLOG 
BY’ LOG 
Bl’ NO_LOG 
bit 3 SSCP_PU_SESSION 
B’0’ SEND 
Bl’ NO_SEND 
bits 4-7 B’0000’ Reserved 
37 1 X’00’ Reserved 
38 2* DATA_LENGTH 
40 n DATA (note 1) 


Note 1: For information on management services data, refer 


to the SNA Format and Protocol Reference Manual under 
Management Services and under User-Defined Data. 
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WAIT 


record format (AH = 2) 


Disp Lng Value Field Name 

0 12 ifs Required APPC/PC area 

12 2° X’1300’ (19) Verb operation code 

14 6 6X00’ Reserved 

20 2 Primary RETURN_CODE 
X’0000’ OK 
X’0001’ PARAMETER _ CHECK 
X’0002’ STATE CHECK 
X’0003’ ALLOCATION ERROR 
X’0006’ DEALLOCATE ABEND PROG 
X’0007’ DEALLOCATE ABEND_SVC 
X’0008’ DEALLOCATE_ABEND_ TIMER 
X’0009’ DEALLOCATE_NORMAL 
X’000A/ DATA_POSTING_BLOCKED 
X’000B’ POSTING_NOT_ACTIVE 
X’000C’ PROG_ERROR_NO_TRUNC 
X’000D’ PROG_ERROR_TRUNC 
X’000E’ PROG_ERROR_PURGING 
X’000F’ CONV_FAILURE_RETRY 
X’0010’ CONV_FAILURE NO_RETRY 
X’0011’ SVC_ERROR_NO_TRUNC 
X’0012’ SVC_ERROR_TRUNC 
X’0013’ SVC_ERROR_ PURGING 
X’0019’ CONVERSATION_TYPE_MIXED 
X’FOOI’ APPC_DISABLED 
X’F002’ APPC_BUSY 
X’F'003’ APPC_ABENDED 
X’F004’ INCOMPLETE 

22 4 Secondary RETURN_CODE 
X’00000000’ POSTED_DATA 
X’00000001’ POSTED _NOT_DATA 

(primary RETURN_CODE - X’0000’) 
X’00000001’ BAD_TP_ID 
(primary RETURN_CODE - X’0001’) 

X’00000002’ BAD_CONV_ID 
X’00000122’ NOT_RCV_STATE 

26 8 TP_ID 

304 4 CONV_POSTED 

38 1 Number of conversations to wait on 

39 4*n CONV_ID_LIST 


For descriptions of the ALLOCATION_ERROR secondary return 
codes, see Chapter 6, “Using Transaction Mapped Conversation 


Verbs,” or Chapter 7, “Using Transaction Basic Conversation 
Verbs.” 
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Appendix B. Conversation State 
Matrices 


This appendix shows the conversation state transitions that can 
occur when a program issues a conversation verb. 


The three causes of state transitions are: 


e Verbs the local program issues 
e Verbs the remote program issues 
e Network errors. 


APPC/PC indicates a state change caused by the remote program 
or a network error by reporting a return code other than OK to 
the local program. For the RECEIVE _AND_ WAIT and 
RECEIVE IMMEDIATE verbs, APPC/PC can also indicate a 
state change on the WHAT_RECEIVED parameter. 


The following figures illustrate the possible conversation state 
transitions in a matrix format. The columns of the matrix show 
the states, and the rows show the verbs. A verb appears more 
than once if there is more than one way for that verb to cause a 
state change. 


The verbs listed in the matrix apply to the basic conversation API 
as well as the mapped conversation API, unless noted otherwise 
by the “not MC” indication next to the verb name. 


APPC/PC defines the following conversation states: 


Reset is the state in which the program can allocate the 
conversation. 


Send is the state in which the program can send data, request 
confirmation, or deallocate a conversation normally. 


Receive is the state in which the program can receive 
information from the remote program. 
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Confirm, Confirm Send, and Confirm Deallocate are the 
states in which the program can reply to a confirmation 
request. (Chapters 1 through 10 refer to this group of states 
as “confirm state.”) 


These matrices use abbreviations for the parameters, return 
codes, and WHAT RECEIVED indications. The definitions for 
the abbreviations and symbols used in the state-transition matrix 
appear at the bottom of the following figure. 


Several return codes (for example, PARAMETER CHECK, 
STATE CHECK, and CONVERSATION TYPE MIXED) are 
valid return codes for almost all verbs but they do not cause a 
state change. Therefore, the matrices do not list these errors 
separately for each verb. 
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Verb Conversation States 


Reset Re- Con- } Con- 
ceive | firm | firm | firm 
Send | De- 


| 
/ 


pot 


Conv Initiated by Partner 
ALLOCATE[ok] 
ALLOCATE[er] 

CONFIRM [ok] 

CONFIRM [er] 


CONFIRM[ep] 
CONFIRMED 
DEALLOCATE(F)[ok] 
- DEALLOCATE(C)[ok] 
DEALLOCATE(A)[ok] 


DEALLOCATE(C)[er] 
DEALLOCATE(C)f{ep] 
FLUSH 
GET_ATTRIBUTES 
GET_TYPE 


POST_ON_RECEIPT (not MC) 
PREPARE_TO_RECEIVE(F)[ok] 
PREPARE_TO_RECEIVE(C)[ok] 
PREPARE_TO_RECEIVE(C){er] 
PREPARE_TO_RECEIVE(C)[ep] 


RECEIVE_AND_WAIT[ok] {da} 
RECEIVE_AND_ WAIT[ok] {se} 
RECEIVE_AND_WAIT[ok]{co} 


1 
a —_— [ ae a ry 
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— 


RECEIVE_AND_WAIT[ok]{cs} 
RECEIVE_AND_WAIT[ok]{cd} 


RECEIVE_AND_ WAIT{[dn] 
RECEIVE_AND_WAIT{da] 
RECEIVE_AND_WAITfer] 
RECEIVE _AND_WAITfep] 
RECEIVE_AND_WAIT{et] 


RECEIVE_IMMEDIATE[ok]{da} 
RECEIVE_IMMEDIATE[ok]{se} 
RECEIVE_IMMEDIATE[ok]{co} 
RECEIVE_IMMEDIATE[ok]{cs} 
RECEIVE_IMMEDIATE[ok]{cd} 


RECEIVE_IMMEDIATE[dn] 
RECEIVE _IMMEDIATE[da] 
RECEIVE_IMMEDIATE[er] 
RECEIVE_IMMEDIATE[ep] 
RECEIVE_IMMEDIATEf[et] 


. te 


fee eae ane see ee ee 
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‘ pt et et POD OTR DO 


eC eS ee eT 
ee i eee 
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Verb Conversation | Verb Conversation States 


Re- Con- | Con- 
ceive | firm | firm | firm 
6 


Reset 


RECEIVE_IMMEDIATE[un] 
REQUEST_TO_SEND 
SEND_DATA[ok] 
SEND_DATAler] 
SEND_DATAlep]| 


SEND_ERROR[ok] 
SEND_ERROR[er] 
SEND_ERROR{[dn] 
SEND_ERROR[ep] 
TEST(P)[ok] 


TEST(P)[un} 
TEST(P)[er] 
TEST(P)[ep] 
TEST (P){et] 
TEST(P){dn] 


TEST(P)[da] 
TEST(Q)[ok] 
TEST(Q)[un] 
WAIT[ok] (Not MC) 
WAIT{[er] 


WAIT[ep] 
WAIT{et] 
WAIT{dn] 
WAIT{da] 


| jee 


~~ ee eee ee tn feo da 


ooa ) ' ' , . 
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Conversation State Transition Matrix Abbreviations 


Parameter Abbreviations (...) 


A 


TYPE(ABEND_ PROG), 
TYPE(ABEND_SVC), 
TYPE(ABEND_ TIMER) if 
basic conversation, or 
TYPE(ABEND) if mapped 
conversation 


TYPE(SYNC_LEVEL) with 
synchronization level 
CONFIRM 

TYPE(FLUSH) 
TEST(POSTED) 


TEST(REQUEST_TO_ 
SEND_RECEIVED) 


Return-Code Abbreviations [...] 


er 


Error on link or when 


allocating a conversation to a 


session or resource failure 


Partner issued a 
SEND_ERROR, data purged 
or no truncation occurred 


Partner issued a 
SEND_ERROR, data 
truncated 


DEALLOCATE issued by 
partner 


UNSUCCESSFUL 


Successful completion of 
command 


Return-Code Abbreviations, 
continued 


da DEALLOCATE_ABEND 
issued by partner 


What-Received Abbreviations {...} 
co CONFIRM issued by partner 
cd Confirm Deallocate (partner 


issued DEALLOCATE using 
Confirm) 


Confirm Send (partner issued 
PREPARE_ TO_RECEIVE 
using CONFIRM) 


DATA received 


SEND (partner issued some 
form of receive) 


Matrix Symbols 


Verb cannot be issued in 
this state 


Remains in current state 


Number of next state 
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Appendix C. Verb Return Codes 


This appendix describes the return codes that APPC/PC can 
report to a program through the RETURN_CODE parameter of 
each verb. The descriptions include the hexadecimal return code 
value, an explanation of the condition causing the return code, 
and the corrective actions required if the return code indicates an 
error condition. 


This appendix includes two sections. The first section describes 
the return codes that are common to most verbs. The second 
section describes the return codes that are unique to each verb 
and lists the common return codes described in the first section. 
These common return codes are: 


ALLOCATION ERROR 
APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 
CONVERSATION TYPE MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DATA POSTING BLOCKED 
DEALLOCATE_ABEND 
DEALLOCATE_ABEND_ PROG 
DEALLOCATE_ABEND_ SVC 
DEALLOCATE_ABEND_ TIMER 
DEALLOCATE_ NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
INVALID VERB 

OK 

POSTING _NOT_ ACTIVE 

PROG ERROR NO_TRUNC 
PROG_ERROR_ PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_ PURGING 
SVC_ERROR_TRUNC. 


The INVALID_VERB return code indicates a problem in 
recognizing a verb. 
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If the problem is due to an incorrectly issued verb, APPC/PC 
cannot identify which verb was intended. Therefore, this return 
code is not listed with each verb. 


Conversation verbs and the CNOS verb return 2-byte primary 
return codes and 4-byte secondary return codes. Control verbs 
(except. CNOS) return 4-byte return codes only. In this appendix, 
bullets indicate primary return codes and dashes indicate 
secondary return codes. 


Common Return Codes 


The following list describes the return codes that are common to 
many verbs. 


e X’00000000’ or X’0000’ OK 
Description: APPC/PC executed the verb as specified. 
Action: No action is required. 

e X’0003’ ALLOCATION_ERROR 


Description: APPC/PC could not properly allocate a 
conversation. 


Action: Check the parameters of the ALLOCATE or 
MC_ALLOCATE verb. 


The ALLOCATION_ERROR secondary return 
codes are: 


— X’00000004" ALLOCATION_FAILURE_NO_RETRY 


Description: APPC/PC cannot allocate the conversation 
on a session because of a permanent 
condition. For example, APPC/PC cannot 
activate the session to be used for the 
conversation because the current mode 
session limit for the specified partner LU is 
0; or because of a system definition error or 
a session-activation protocol error before it 
could allocate the conversation. 
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Action: 


X’00000005’ 


Description: 


Action: 


The program should not try the 
conversation again until the condition is 
corrected. APPC/PC reports this return 
code on the ALLOCATE or 
MC_ALLOCATE requesting the 
conversation. 


For the IBM Token-Ring Network adapter, 
check that the adapter number setting in 
the IBM Token-Ring configuration menu 
matches the switch setting on the adapter 
card and the partner LU address specified 
on the ATTACH LU verb. For SDLC, 
check that any modems are properly 
plugged. Check that the station role in the 
SDLC configuration menu is properly set at 
primary, secondary, or negotiable, and that 
this corresponds to the settings at the 
partner node. If host-connected, the PC 
must be secondary. Check that the NRZI 
setting in the SDLC configuration menu 
matches the NRZI setting of the partner 
node. Restart APPC/PC by unloading and 
then reloading it. 


ALLOCATION_FAILURE_RETRY 


APPC/PC cannot allocate the conversation 
on a session because of a temporary 
condition. For example, APPC/PC cannot 
activate the session to be used for the 
conversation because of a temporary lack of 
resources at the local LU or because 
APPC/PC deactivated the session in 
response to a line or modem failure before it 
could allocate the conversation. The 
program can try the conversation again. 
APPC/PC reports this return code on the 
ALLOCATE or MC_ALLOCATE requesting 
the conversation. 


For the IBM Token-Ring Network adapter, 
check that the adapter number setting in 
the IBM Token-Ring configuration menu 
matches the switch setting on the adapter 
card and the partner LU address specified 
on the ATTACH_LU verb. For SDLC, 
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X’10086034’ 


Description: 


Action: 


X’10086031’ 


Description: 


Action: 


check that any modems are properly 
plugged. Check that the station role in the 
SDLC configuration menu is properly set at 
primary, secondary, or negotiable, and that 
this corresponds to the settings at the 
partner node. If host-connected, an IBM PC 
must be secondary. Check that the NRZI 
setting in the SDLC configuration menu 
matches the NRZI setting of the partner 
node. 


Reissue the ALLOCATE or 
MC_ALLOCATE verb. However, to avoid 
congesting the network with attempted 
allocation requests, the program should 
pause or wait for a keystroke before 
retrying the conversation. 


CONVERSATION_TYPE_ MISMATCH 


The remote LU rejected the allocation 
request because it or the remote transaction 
program does not support the specified 
conversation type. APPC/PC reports this 
return code on a verb issued after the 
ALLOCATE or MC_ ALLOCATE verb. 


Change the transaction program so that it 
uses the other conversation type (basic or 
mapped). 


PIP_NOT_ALLOWED 


The remote LU rejected the allocation 
request because the local transaction 
program specified program initialization 
parameters and either the remote LU does 
not support PIP data or the remote 
transaction program has no PIP variables 
defined. APPC/PC reports this return code 
on a verb issued after the ALLOCATE or 
MC_ALLOCATE verb. 


Do not use PIP data. 


X’10086032’ 


Description: 


Action: 


X’080F 6051’ 


Description: 


Action: 


X’10086041’ 


Description: 


Action: 


PIP_NOT_SPECIFIED CORRECTLY 


The remote LU rejected the allocation 
request because the remote transaction 
program has one or more PIP variables 
defined and the local transaction program 
has specified that no PIP variables are to be 
used. This secondary return code can also 
indicate that the number of PIP variables 
defined by the local transaction program is 
different than the number specified by the 
remote transaction program. APPC/PC 
reports this return code on a verb issued 
after the ALLOCATE or MC_ALLOCATE 
verb. 


Specify that PIP data is to be used with the 
PIP(YES) parameter on the 
MC_ALLOCATE or ALLOCATE verb and 
make sure that the number of PIP variables 
agrees with the number defined for the 
remote transaction program. 


SECURITY_NOT_VALID 


The remote LU rejected the user ID or 
password supplied on the ALLOCATE or 
MC_ALLOCATE verb. APPC/PC reports 
this return code on a verb issued after the 
ALLOCATE or MC_ALLOCATE verb. 


Request the operator to re-enter the user ID 
and password. 


SYNC_LEVEL_NOT_SUPPORTED 


The remote program rejected the 
allocation request because the local 
transaction program specified an 
unrecognized or unacceptable 
SYNC_LEVEL type. APPC/PC reports this 
return code on a verb issued after the 
ALLOCATE or MC_ALLOCATE verb. 


Change the SYNC_LEVEL specification. 
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— X’10086021’ TPN_NOT_RECOGNIZED 


Description: The remote LU rejected the allocation 
request because the local transaction 
program specified a remote transaction 
program name that the remote LU does not 
recognize. This return code can also 
indicate that the remote LU recognized the 
TPN but could not initiate the TPN using 
the designated partner LU or mode name. 


Action: Check the validity of the program name and 
the designated partner LU and mode names. 


— X/’084C0000’ TRANS_PGM_NOT_AVAIL_NO_RETRY 


Description: The remote LU rejected the allocation 
request because it cannot start the specified 
transaction program. APPC/PC reports this 
return code on a verb issued after the 
ALLOCATE or MC_ALLOCATE verb. 


Action: Do not retry the allocation request. 
Consult the system operator. 


— X’084B6031’ TRANS_PGM_NOT_AVAIL_ RETRY 


Description: The remote LU rejected the allocation 
request because it cannot start the specified 
transaction program immediately. 
APPC/PC reports this return code on a verb 
issued after the ALLOCATE or 
MC_ALLOCATE verb. 


Action: Retry the allocation request. However, to 
avoid congesting the network with 
attempted allocation requests, the program 
should pause or wait for a keystroke before 
retrying the conversation. 


e X’F0010000’ or X’F001’ APPC_DISABLED 
Description: APPC/PC did not execute the verb because 


APPC/PC was disabled by the 
DISABLE/ENABLE_APPC verb. 
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Action: Issue the DISABLE/ENABLE_APPC verb to 
re-enable APPC/PC. 


X’F0020000’ or X’F002’ APPC_BUSY 


Description: APPC/PC did not execute the verb because 
APPC/PC was processing another verb. 
APPC/PC can process only one verb at a time. 
This error can occur if a hardware interrupt 
during APPC/PC processing calls a routine that 
issues an APPC/PC verb. 


Action: Wait until APPC/PC is not busy and then 
reissue the verb. 


X’F0030000’ or X’ F003’ APPC_ABENDED 


Description: APPC/PC did not execute the verb because 
APPC/PC has abnormally terminated. 


Action: Restart APPC/PC by unloading and then 
reloading it. 


X’0019’ CONVERSATION_TYPE_MIXED 


Description: The program issued both basic and mapped 
conversation verbs on the same conversation. 


Action: Change the transaction program so that it 
issues only one type of conversation verb on 
this conversation. 


X’0010’ CONV_FAILURE_NO_RETRY 


Description: A permanent failure prematurely terminated 
the conversation. 


Action: The condition is not temporary; operator 
intervention is necessary to correct the 
problem. 

X’000F’ CONV_FAILURE_ RETRY 


Description: A temporary failure prematurely terminated 
the conversation. 


Action: Allocate conversation again. 
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e X’000A’ DATA_POSTING_BLOCKED 


Description: APPC/PC cannot post one of the active 
conversations because the APPC/PC internal 
workspace storage is in use and the program is 
unable to send a pacing response. The 
condition is temporary. APPC/PC can report 
this return code on the WAIT and TEST verbs. 


Action: The transaction program can still issue any 
verb but it should issue 
RECEIVE. IMMEDIATE or 
RECEIVE AND_ WAIT to free some space so 
that APPC/PC can resume posting active 
conversations. 


Alternatively, you can reconfigure APPC/PC to 
provide a larger MAX RU_SIZE, a larger 
receive pacing window size, or no pacing at all. 
If you use receive pacing and issue a TEST or 
WAIT for more than R(P-1) bytes of data (where 
P = pacing window and R = negotiated 
maximum RU size for the session), APPC/PC 
may report a buffer full condition with this 
return code. Even this amount of data may be 
too large if the partner transaction program 
issues the FLUSH verb between SEND_ DATA 
verbs causing messages of less than the 
maximum RU size to flow on the line. If pacing 
is not used, APPC/PC cannot control the flow of 
data sent by the partner transaction program. 
If its workspace storage becomes full APPC/PC 
abnormally terminates and rejects subsequent 
verbs. 


e X’0005’ DEALLOCATE_ ABEND 


Description: The source of the error notification is either 
the remote transaction program or the remote 
LU. The remote transaction program causes 
this error notification by issuing an 
MC_DEALLOCATE verb specifying the 
TYPE(ABEND) parameter. Alternatively, the 
remote LU can issue an MC_DEALLOCATE 
because of a remote transaction program 
ABEND condition. 
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Action: Check the transaction program for errors. 
e X’0006’ DEALLOCATE_ABEND PROG 


Description: The remote transaction program or the remote 
LU causes this error notification by issuing a 
DEALLOCATE verb specifying the 
TYPE(ABEND_PROG) parameter. If the 
conversation for the remote transaction 
program is in receive state when the 
DEALLOCATE occurs, information sent by the 
local transaction program, and not yet received 
by the remote transaction program, is purged. 


APPC/PC reports this return code on a verb the 
program issues in send or receive state when 
the remote transaction program or remote LU 
deallocates the conversation. 


Action: Check the transaction program for errors. 
e X’0007’ DEALLOCATE_ABEND_ SVC 


Description: The remote transaction program or the remote 
LU causes this error notification by issuing a 
DEALLOCATE verb specifying the 
TYPE(ABEND_SVC) parameter. If the 
conversation for the remote transaction 
program is in receive state when the 
DEALLOCATE occurs, information sent by the 
local program, and not yet received by the 
remote program, is purged. 


APPC/PC reports this return code on a verb the 
program issues in send or receive state when 
the remote program or remote LU deallocates 
the conversation. 


Action: Check the transaction program for errors. 
e X’0008’ DEALLOCATE ABEND_ TIMER 


Description: The remote transaction program causes this 
error notification by issuing a DEALLOCATE 
verb specifying the TYPE(ABEND_ TIMER) 
parameter. If the conversation for the remote 
transaction program is in receive state when 


Action: 


the DEALLOCATE occurs, information sent by 
the local transaction program, and not yet 
received by the remote transaction program, is 
purged. 


APPC/PC reports this return code on a verb the 
transaction program issues in send or receive 
state when the remote transaction program or 
remote LU deallocates the conversation. 


Check the transaction program for errors. 


e X’0009’ DEALLOCATE_NORMAL 


Description: 


Action: 


Description: 


Action: 


The remote transaction program issued a 
DEALLOCATE specifying the 
TYPE(SYNC_LEVEL) or TYPE(FLUSH) 
parameter. APPC/PC reports this return code 
on a verb the local transaction program issues 
in receive state. 


This return code is not an error indication. 


X’F0040000’ or X’F004’ INCOMPLETE 


The issued verb has suspended without 
completing its defined function. 


To avoid a deadlock situation (as described 
under “System Deadlocks” on page 10-2), issue 
verbs on any other active transaction programs, 
and then issue one or more GET ALLOCATE 
verbs to process incoming ALLOCATEs queued 
in any LU. Then re-issue the current verb 
without changing any parameter, (except for the 
first 12 bytes which you can use to store list 
pointers to maintain a list of incomplete verbs). 


e X’F0050000’ or X’F005’ INCOMPLETE_ALTERED_VERB 


Description: 


C-10 


A verb that has previously returned as 
INCOMPLETE was altered when it was 
re-issued. You may have changed the verb, or 
issued a new verb from the same transaction 
program before re-issuing the incomplete verb. 


Action: Alter the transaction program so that no verb 
other than the unchanged incomplete verb 
(except for the first 12 bytes) is issued from that 
program. 


@ X’FFFFFFFF’ or X’FFFF’ INVALID VERB 


Description: APPC/PC did not recognize the supplied verb 
operation code and did not execute the verb. 
An incorrect AH value can also cause this 
return code. 


Action: Correct the operation code or the AH value. 
e X’000B’ POSTING _NOT_ACTIVE 


Description: Posting is not active for the specified 
conversations. 


Action: Issue POST_ON_RECEIPT before testing the 
conversation. 


e X’000C’ PROG_ERROR_NO_TRUNC 


Description: The remote transaction program issued a 
SEND_ERROR specifying the TYPE(PROG) 
parameter, the conversation for the remote 
transaction program was in send state, and the 
SEND_ERROR did not truncate a logical 
record. No truncation occurs when a program 
issues SEND_ERROR before sending any 
logical records or after sending a complete 
logical record. 


APPC/PC reports this return code on a receive 
verb and the conversation remains in receive 
state. 


Action: Check the error. 
e X’000K’ PROG _ ERROR PURGING 
Description: The remote transaction program issued a 
SEND_ERROR verb specifying the 
TYPE(PROG) parameter in receive or confirm 


state. If the remote transaction program issues 
a SEND_ERROR verb when it is in receive 
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Action: 


e X’000D’ 


state, information sent to, but not yet received 
by, the remote transaction program is purged. 


APPC/PC normally reports this return code on 
a verb the local transaction program issues 
after sending information to the remote 
transaction program. However, APPC/PC can 
also report this return code on a verb the 
program issues before sending any information, 
depending on the verb and when the program 
issues it. The conversation remains in receive 
state. 


Check the error and prepare to resend data that 
may have been lost. 


PROG_ERROR_TRUNC 


Description: The remote transaction program issued a 


Action: 


e X’0011’ 


SEND_ERROR specifying the TYPE(PROG) 
parameter, the conversation for the remote 
transaction program was in send state, and the 
SEND_ERROR truncated a logical record. 
Truncation occurs when a program begins 
sending a logical record and then issues 
SEND_ERROR before sending the complete 
logical record. APPC/PC reports this return 
code on a RECEIVE AND WAIT or 
RECEIVE_IMMEDIATE verb the local 
transaction program issues after receiving the 
truncated logical record. 


Check the error. 


SVC_ERROR_NO_TRUNC 


Description: The remote transaction program or remote LU 
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issued a SEND_ERROR specifying the 
TYPE(SVC) parameter, the conversation for the 
remote transaction program was in send state, 
and the SEND_ ERROR did not truncate a 
logical record. No truncation occurs when a 
program issues SEND_ERROR before sending 
any logical records or after sending a complete 
logical record. 


Action: 


e X’0013’ 


APPC/PC reports this return code on a receive 
verb and the conversation remains in receive 
state. 


Check the error. 


SVC_ERROR_PURGING 


Description: The remote transaction program or remote LU 


Action: 


e X’0012’ 


issued a SEND_ERROR specifying the 
TYPE(SVC) parameter in receive or confirm 
state. If the remote transaction program issues 
a SEND_ERROR verb when it is in receive 
state, information sent to, but not yet received 
by, the remote transaction program is purged. 


APPC/PC reports this return code on a verb the 
local transaction program issues after sending 
information to the remote transaction program. 
However, APPC/PC can also report this return 
code on a verb the program issues before 
sending any information, depending on the verb 
and when the program issues it. The 
conversation remains in receive state. 


Check the error and prepare to resend the data 
that may have been purged. 


SVC_ERROR_TRUNC 


Description: The remote transaction program or remote LU 


Action: 


issued a SEND_ERROR specifying the 
TYPE(SVC) parameter, the conversation for the 
remote transaction program was in send state, 
and the SEND_ ERROR truncated a logical 
record. Truncation occurs when a program 
begins sending a logical record and then the 
program or LU issues SEND_ERROR before 
sending a complete logical record. APPC/PC 
reports this return code on a 
RECEIVE_AND_WAIT or 
RECEIVE_IMMEDIATE verb the local 
transaction program issues after receiving the 
truncated logical record. 


Check the error. 


C-13 


Verb-Specific Return Codes 


The rest of this appendix describes the return codes for all verbs, 
arranged in alphabetic order by verb name. 


ACTIVATE_DLC 


e X’00000008’ 


Description: 


Action: 
e X’00000283’ 


Description: 


Action: 
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NO_PU_ATTACHED 


APPC/PC has not yet received a valid 
ATTACH_PU verb. 


Issue an ATTACH PU verb. 
DLC_ FAILURE 


This return code indicates one of many 
possible error conditions. For example, the 
adapter number may have been incorrectly 
specified on the APPC/PC configuration menus 
or on the ATTACH LU verb. This return code 
can also indicate that the adapter address for 
the IBM Token-Ring Network exists elsewhere 
on the token ring. 


If the adapter is for the IBM Token-Ring 
Network, check switch 2 (the 
primary/secondary adapter switch) and verify 
that it matches the adapter number parameters 
specified on the ACTIVATE DLC and 
ATTACH _LU verbs, and the adapter number 
entry on the APPC/PC configuration menus. 


If another program which uses the IBM 
Token-Ring Network adapter (such as the 
NETBIOS program) was loaded before 
APPC/PC, you may have to reload the other 
program again, specifying an adequate number 
of service access points and links for APPC/PC 
operation. For more information of Service 
Access Point (SAP) operation, see the JBM 
Token-Ring Network NETBIOS Program User’s 
Guide. For information on loading APPC/PC, 


X’00000284’ 


Description: 


Action: 


X’00000286’ 
Description: 


Action: 


refer to the APPC/PC Installation and 
Configuration Guide. 


If you unloaded APPC/PC and moved to another 
IBM PC in the same token ring after your 
program issued ACTIVATE DLC, you must use 
a new soft address on the new IBM PC. 
Alternatively, you can free the original soft 
address by turning off the first IBM PC or by 
re-initializing the first IBM PC with the adapter 
diagnostic program after unloading APPC/PC. 
This program is supplied with the IBM 
Token-Ring Network adapter. 


Check the SYSLOG entry for error information 
on DLC failures. 


UNRECOGNIZED_ DLC 
APPC/PC could not find the specified DLC 
name and adapter number in the configuration 


file. 


Check the DLC name and adapter number 
supplied in the configuration file. 


DUPLICATE_DLC 
The specified DLC is already open. 
Check the DLC name and adapter number on 


the ACTIVATE DLC verb to see if they are 
correct. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F0030000’ 
X’F0020000’ 
X’F 0010000’ 
X’00000000’ 


APPC_ABENDED 
APPC_BUSY 
APPC_ DISABLED 
OK. 


C-15 


ALLOCATE and MC_ALLOCATE 


e X’0001’ 
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X’00000001’ 


Description: 


Action: 


X’00000006’ 


Description: 


Action: 


X’00000010’ 


Description: 


Action: 
X’00000011’ 


Description: 


Action: 


PARAMETER_CHECK 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 

TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


DATA_AREA_ACROSS_SEGMENT 


APPC/PC does not permit PIP data to 
cross a segment boundary. 


Recalculate the segment and offset registers 
so that offset registers will not wrap back 
around to 0. 


BAD_TPN_LEN 


The value that TPN LENGTH specifies is 
too short (less than 1) or too long (greater 
than 64). 


Check the TPN LENGTH value. 
BAD_CONV_TYPE 


APPC/PC does not recognize the specified 
conversation TYPE. 


Check the conversation TYPE field. The 
only valid values are X’00’ for 
BASIC_CONVERSATION and X’01’ for 
MAPPED CONVERSATION. 


X’00000012’ 


Description: 


Action: 


X’00000013’ 


Description: 


Action: 


X’00000014’ 


Description: 


Action: 


X’00000015’ 


Description: 


Action: 
X’00000016’ 


Description: 


Action: 


BAD_SYNC_LEVEL 


APPC/PC does not recognize the specified 
SYNC_LEVEL type. 


Check the SYNC_LEVEL type field. The 

only valid values are X’00’ for NONE and 

X’01’ for CONFIRM. 
BAD_SECURITY_SELEC 


APPC/PC does not recognize the specified 
SECURITY type. 


Check the SECURITY type field. The only 
valid values are X’00’ for NO__ 
CONVERSATION LEVEL SECURITY, 
X’01’ for SAME, and X’02’ for PGM. 

BAD RETURN_CONTROL 


APPC/PC does not recognize the specified 
RETURN_CONTROL value. 


Check the RETURN_CONTROL field. The 
only valid values are X’00’ for 
WHEN_SESSION_ALLOCATED, X’01’ for 
IMMEDIATE, and X’02’ for 
WHEN_SESSION_ FREE. 
TOO_BIG_SEC_TOKENS 


APPC/PC does not accept a password or a 
user ID that is greater than 8 bytes. 


Check length of password or user ID. 
PIP_LEN INCORRECT 


APPC/PC does not accept PIP data that is 
longer than 32767 bytes. 


Make sure that the PIP data is not longer 
than 32767 bytes. 
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— X’00000017’ NO_USE_OF_SNASVCMG 


Peperaptign: APPC/PC does not permit the EBCDIC 


Action: 


mode name SNASVCMG with the 
ALLOCATE or MC_ ALLOCATE verbs. 


Check the mode name. 


— X’00000018’ UNKNOWN_PARTNER_ MODE 


Description: APPC/PC does not recognize the specified 


Action: 


e <X’0014’ 


partner LU or mode name. 


Check the partner LU and mode name 
specified for the ATTACH LU verb. The 
partner LU and mode names must be the 
same as specified for the ATTACH LU 
verb. 


UNSUCCESSFUL 


Description: The program specified 


Action: 


RETURN_CONTROLUMMEDIATE) on the 
allocation request and APPC/PC could not 
allocate the conversation because no 
contention-winner sessions were available. 


Use the CNOS verb to increase the number of 
available contention-winner sessions or issue 
the allocation request with a 
RETURN_CONTROL 

(WHEN SESSION _ ACTIVATED) or 
RETURN_CONTROL 

(WHEN _SESSION_FREE) parameter. Check 
the previously issued verbs for error conditions, 
check all verb parameters for validity, and then 
resend the verb. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 003’ 
X’F002’ 
X’F001’ 
X’0003’ 
X’F 004’ 
X’F005’ 
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APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 

ALLOCATION ERROR 
INCOMPLETE 

INCOMPLETE _ALTERED_VERB 


X’0000’ OK. 


ATTACH_LU 


X’00000008’ 


Description: 


Action: © 
X’00000211’ 
Description: 


Action: 


X’00000212’ 


Description: 


Action: 


X’00000213’ 


Description: 


Action: 
X’00000214’ 


Description: 


NO_PU_ATTACHED 


The PU is not defined because APPC/PC has 
not yet received a valid ATTACH PU verb. 


Issue an ATTACH PU verb. 
ALREADY _ ACTIVE _LU 
The LU is already defined. 


Do not attempt to attach two LUs with the 
same name. 


BAD_PART_SESS 


The session limit for an individual partner LU 
(PARTNER _LU_SESSION_LIMIT) is greater 
than the session limit permitted for all partner 
LUs (LU_SESSION_ LIMIT). 


Increase the session limit for all partner LUs 
(LU_SESSION_ LIMIT) to accommodate the 
specified session limit for the partner LU (that 
is, the PARTNER LU SESSION_LIMIT) or 
decrease the session limit for the partner LU. 


BAD_RU_SIZES 


The maximum RU size value of the 
MAX _ RU_SIZE parameter is smaller than the 
minimum RU size value. 


Reverse the values of the RU sizes. 

BAD _MODE_SESS 

The session limit for an individual mode name 
(MODE _MAX NEGOTIABLE_ SESSION __ 


LIMIT) is greater than the session limit 
(PARTNER _ LU _SESSION_ LIMIT) permitted 
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Action: 


e X’00000216’ 


Description: 


Action: 


e X’00000219’ 


Description: 


Action: 


e X’0000021A’ 


Description: 


Action: 
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for all mode names used for sessions with the 
specific partner LU. 


Increase the PARTNER_LU_SESSION_LIMIT 
or decrease the session limit of the individual 
mode name 

(MODE_MAX NEGOTIABLE SESSION _ 
LIMIT). 


BAD_PACING_CNT 


The PACING_SIZE is not in the range of 0 to 
63, inclusive. 


Check the pacing size. Increase or decrease 
this size to fit within the specified range. 


EXTREME_RUS 


The upper bound for the MAX RU_ SIZE size 
is too large or the lower bound is too small. 


The low value must be at least 16, and the high 
value must not be more than allowed by the 
link station that is to carry the session traffic 
(specified as the MAX RU_SIZE value in the 
configuration file). In the most general 
environment, you should have low value less 
than or equal to 256 and high value greater 
than or equal to 256. 


SNASVCMG_1 


APPC/PC does not accept the EBCDIC name 
“SNASVCMG” as the mode name for a single 
session connection to communicate data 
between transaction programs. 


Using the mode name “SNASVCMG” implies 
parallel sessions are being used. Therefore, a 
single session connection cannot use the 
“SNASVCMG” mode name. 


e X’00000284’ 


UNRECOGNIZED_DLC 


Description: APPC/PC could not find the specified DLC 


Action: 


name and adapter number. 


Check the DLC name and adapter number 
supplied on the APPC/PC configuration menus. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F0030000’ 
X’F 0020000’ 
X’F 0010000’ 
X’00000000’ 


ATTACH_PU 


e X’00000201’ 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


ALREADY_ACTIVE_PU 


Description: The PU is already active and cannot be 


Action: 


redefined at this time. This error can result if a 
previous DETACH _PU has not completed. 


Wait for APPC/PC to complete execution of a 
previous DETACH_PU verb or issue the 
DETACH PU immediately before the 
ATTACH _LU verb. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 0030000’ 
X’F 0020000’ 
X’F 0010000’ 
X’00000000’ 


CHANGE_LU 
e X’00000003’ 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


BAD_LU_ID 


Description: APPC/PC does not recognize the specified 


LU_ID. 
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Action: Match this LU_ID with the one APPC returns 
after executing the ATTACH _LU verb. 


e X’00000230’ INVALID_CHANGE 


Description: The application subsystem has made an 
invalid change in the management of incoming 
ALLOCATEs. 


Action: Check the exit pointer. You cannot change the 
synchronous or asynchronous handling of 
incoming ALLOCATEs. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 0030000’ APPC_ABENDED 
X’F 0020000’ APPC_BUSY 

X’F 0010000’ APPC_ DISABLED 
X’00000000’ OK. 


CNOS 
e X’0000’ OK 
— X’00000000’ CNOS_ACCEPTED 


Description: APPC/PC executed the CNOS verb 
successfully as specified. 


Action: This return code is not an error condition, 
just a positive response. 


— ‘00000001’ CNOS_ NEGOTIATED 


Description: APPC/PC executed the CNOS verb 
successfully as negotiated by the partner 
LU. 


Action: This return code is not an error condition. 
It indicates that one or more parameter 
values have been negotiated. The program 
can obtain the negotiated values by issuing 
the DISPLAY verb. 
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e X’0001’ 


X’00000003’ 


Description: 


Action: 


X’00000153’ 


Description: 


Action: 


X’00000154’ 


Description: 


Action: 


PARAMETER_CHECK 


BAD LU_ID 


APPC/PC does not recognize the specified 
LU_ID. 


Match this LU_ID with the one APPC/PC 
returns after executing the ATTACH LU 
verb. 


ALL_MODE_MUST_RESET 


APPC/PC does not permit the specification 
of a non-0 session limit when the 
MODE _NAME_ SELECT parameter 
indicates ALL. 


When setting the MODE NAME SELECT 
parameter to ALL, you must set the session 
limits to 0. Set limits to 0 or check the 
MODE NAME_ SELECT parameter. 


BAD_SNASVCMG_LIMITS 


The application subsystem has specified 
invalid settings for the 
PARTNER _LU_MODE_SESSION _ 
LIMIT, MIN. CONWINNERS_SOURCE, or 
MIN _CONWINNERS_TARGET parameters 
when MODE_ NAME(SNASVCMG) is 
indicated. 


The three groups of valid settings for the 
SNASVCMG mode are as follows: 


— PARTNER _LU_MODE_SESSION_ 
LIMIT(2) 

MIN_CONWINNERS_SOURCKE(1) 

MIN_CONWINNERS_TARGET(1) 


— PARTNER_LU_MODE_ SESSION _ 
LIMIT(1) 

MIN_CONWINNERS_SOURCE(0) 

MIN_CONWINNERS_TARGET(1) 
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X’00000155’ 


Description: 


Action: 


X’00000156’ 


Description: 


Action: 


X’00000157’ 


Description: 


Action: 


X’00000159’ 


Description: 


Action: 


X’0000015A’ 


Description: 


— PARTNER _LU_MODE_SESSION __ 
LIMIT(0) 

MIN_CONWINNERS_SOURCE(0) 

MIN_CONWINNERS_TARGET(0) 


MINS_GT_TOTAL 


The sum of 
MIN _CONWINNERS_SOURCE and 
MIN_CONWINNERS_ TARGET is greater 
than the value specified for the 
PARTNER _LU_MODE_SESSION_ LIMIT. 


Check values of these three fields. 
MODE_CLOSED 
CNOS cannot set a non-0 limit because the 
local maximum negotiable session limit is 


currently 0 for the specified mode. 


Issue the CNOS with SET_ NEGOTIABLE 
= YES. 


BAD_MODENAME 


The specified partner LU does not support 
the specified MODE_ NAME. 


Match the MODE_NAME with the 
MODE_NAME specified with the 
ATTACH _LU verb. 


RESET_SNA_DRAINS 


The SNASVCMG mode does not support 
the DRAIN settings (CNOS). 


Do not set the DRAIN SOURCE and the 
DRAIN_TARGET parameters when using 
CNOS with SNASVCMG mode. 


SINGLE_NOT_SRC_RESP 
For a single session mode (for which 


PARTNER LU SESSION LIMIT = 1) or 
the SNASVCMG mode, APPC/PC permits 


only the local LU to be responsible for 
deactivating sessions. 


Action: Change the value of the RESPONSIBLE 
parameter to SOURCE. 


X’0000015B’ BAD_PARTNER_LU 


Description: APPC/PC does not recognize the specified 
partner LU name. 


Action: The specified PARTNER LU NAME must 
be one of the PARTNER LU NAMEs 
defined by the ATTACH LU verb. Check 
the PARTNER LU NAME value specified 
with the CNOS verb or add the 
PARTNER LU NAME in the 
ATTACH _ LU definition. 


X’0000015C’ EXCEEDS _MAX ALLOWED 


Description: The local maximum negotiable session 
limit is less than the session limit specified 
with the CNOS verb. 


Action: Increase the local maximum session limit 
(MODE _ MAX NEGOTIABLE SESSION __ 
LIMIT) determined by the ATTACH LU 
verb, decrease the session limit 
(PARTNER LU MODE SESSION_LIMIT) 
specified with the CNOS verb or use the 
SET_NEGOTIABLE(YES) option. 


X’0000015D’ CHANGE_SRC_DRAINS 


Description: APPC/PC does not permit a program to 
specify MODE_ NAME_SELECT(ONE) and 
DRAIN_SOURCE(YES) when 
DRAIN _SOURCE(NO) is currently in effect 
for the specified mode. 


Action: A previous CNOS has set session limits to 0 
without draining the source. After this 
action, a program cannot change the drain 
option. 
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© X’0002’ STATE CHECK 
— ‘00000151’ CNOS_SESSLIM_NOT_ZERO 


Description: APPC/PC does not permit a program to 
change the session limit to a non-0 value 
unless the limit is already 0. 


Action: Reset the session limit by issuing the CNOS 
verb with 
PARTNER _LU MODE_SESSION_LIMIT=' 


e X’0018’ CNOS_PARTNER_ REJECT 


Description: The partner LU rejected a CNOS request from 
the local LU because of a condition specified in 
one of the secondary return codes. 


Action: Take the action described for the indicated 
secondary return code. 


— X’00000156’ CNOS_MODE_CLOSED 


Description: The local LU cannot negotiate a non-0 
session because the local maximum session 
limit of the partner LU is 0. 


Action: Check the session limit for the specified 
mode name on the remote LU. 


— 00000157’ CNOS_BAD_MODENAME 


Description: The partner LU does not recognize the 
specified MODE_ NAME. 


Action: Check the partner LU MODE_ NAME on 
the remote system. 


— X’0000015F’ CNOS_COMMAND_RACE_REJECT 


Description: APPC/PC is currently processing a CNOS 
verb issued by the partner LU. 


Action: This is not an error condition. This 
secondary return code simply indicates that 
a race condition occurred during CNOS 
negotiation between two LUs. The program 
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can issue the DISPLAY verb to obtain the 
negotiated values. You may reissue the 


CNOS verb. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F003’ 
X’F002’ 
X’F001’ 
X’0000’ OK. 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 


CONFIRM and MC_CONFIRM 


e X’0001’ 


X’00000001’ 


Description: 


Action: 


X’00000002’ 


Description: 


Action: 
X’00000031’ 


Description: 


Action: 


PARAMETER _CHECK 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 

TP STARTED verb for a locally initiated 
TP or the CREATE TP record for a 
remotely initiated TP. 


BAD_CONV_ID 


APPC/PC does not recognize the specified 
CONV_ ID. 


Check the CONV_ID parameter for validity. 
CONFIRM_ON_SYNC_NONE 
APPC/PC does not permit the program to 
use this verb if it allocated the conversation 
with SYNC_LEVEL(NONE). 
The program can issue a CONFIRM or 


MC_CONFIRM verb only when the 
SYNC_LEVEL is confirm. 
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e X’0002’ STATE_CHECK 
— ‘00000032’ CONFIRM_BAD_ STATE 
Description: The conversation is not in send state. 
Action: Issue the verb in send state. 
— X’00000033’ CONFIRM_NOT_LL_ BDY 


Description: The conversation is in send state, and the 
program started, but did not finish, sending 
a logical record. 


Action: Finish sending a logical record before 
issuing CONFIRM. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0003’ ALLOCATION_ERROR 

X’F003 APPC_ABENDED 

X’F 002’ APPC_BUSY 

X’F001’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_MIXED 
X’0010’ CONV_FAILURE_NO_RETRY 
X’000F”’ CONV_FAILURE_RETRY 
X’0005’ DEALLOCATE_ABEND 

X’0006’ DEALLOCATE_ABEND_ PROG 
X’0007’ DEALLOCATE_ABEND_SVC 
X’0008’ DEALLOCATE_ABEND_ TIMER 
X’F004’ INCOMPLETE 

X’F 005’ INCOMPLETE_ALTERED_VERB 
X’0000’ OK 

X’000E’ PROG_ERROR_PURGING 
X’0013’ SVC_ERROR_PURGING. 


CONFIRMED and MC_CONFIRMED 
e X’0001’ PARAMETER CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 
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Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
e X’0002’ STATE CHECK 
— X’00000041’ CONFIRMED _BAD_ STATE 
Description: The conversation is not in confirm state. 
Action: The local transaction program can issue a 
CONFIRMED only as a reply toa 
confirmation request from the remote LU. 


Check the transaction program for errors. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e X’F003’ APPC_ABENDED 

@ X’F002’ APPC_BUSY 

e X’F001’ APPC_DISABLED 

e X’0019’ CONVERSATION_TYPE_MIXED 
e X’F004’ INCOMPLETE 

e X’F005’ INCOMPLETE_ALTERED_VERB 
e X’0000’ OK. 

CONVERT 


e X’00000401’ INVALID_ DIRECTION 


Description: APPC/PC does not recognize the specified 
conversion DIRECTION. 


Action: Check the value supplied in the DIRECTION 
parameter. 
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e X’00000402’ 


Description: 


Action: 


e X’00000403’ 


Description: 


Action: 


e X’00000404’ 


Description: 


Action: 


e X’00000405’ 


Description: 


Action: 


e X’00000406’ 


Description: 


Action: 
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INVALID_TYPE 


APPC/PC does not recognize the 
CHARACTER_ SET type for conversion. 


Check the value supplied in the 
CHARACTER _ SET parameter. 


SEGMENT_OVERLAP 


The area containing characters to be 
converted or the area that is to contain the 
converted characters overlaps a segment 
boundary. 


Make sure the SOURCE or TARGET offset plus 
the LENGTH value does not exceed 65535. 
Alternatively, you can reduce the number of 
bytes to be converted. 


INVALID_FIRST_CHARACTER 


APPC/PC detected an invalid first character 
for a type “A” conversion. 


Make the first character in the SOURCE buffer 
an uppercase letter or one of the special 
characters, $, #, or @. 


TABLE_ERROR 


APPC/PC could not find the type G conversion 
table. 


Reload APPC/PC and make sure that the file 
containing the type G conversion table is in the 
same directory as APPC/PC. Also make sure 
that the name of the file is the same as that 
specified on the APPC/PC configuration menus. 


CONVERSION_ERROR 


The CONVERT verb found an unrecognized 
character and converted it to X’00’. 


Check the characters in the source string. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F0030000’ APPC_ABENDED 
X’F 0020000’ APPC_BUSY 

X’F 0010000’ APPC_DISABLED 
X’00000000’ OK. 


DEALLOCATE and MC_DEALLOCATE 


e X’0001’ PARAMETER_CHECK 


X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 


TP or the CREATE_TP record for a 
remotely initiated TP. 


X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
X’00000006’ DATA AREA ACROSS_ SEGMENT 


Description: The log data area crosses a segment 
boundary. 


Action: Make sure the offset of the LOG_DATA 
address plus the LOG_DATA_ LENGTH 
does not exceed 65535. 

X’00000051’ DEALLOC_BAD_ TYPE 


Description: APPC/PC does not recognize the specified 
TYPE. 
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e X’0002’ 
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Action: 


X’00000057’ 


Description: 


Action: 


X’00000052’ 


Description: 


Action: 
X’00000053’ 


Description: 


Action: 
X’00000055’ 


Description: 


Check the value of the TYPE field. The 
only valid values for DEALLOCATE are 
X’00’, X’01’, X’02’, X’03’, and X’04’. The only 
valid values for MC_ DEALLOCATE are 
X’00’, X’01’, and X’05’. 

LOG_LL_ WRONG 

The LOG_DATA_ LENGTH does not 
match the value on the LL field of the 
LOG_DATA. 


Check the length of the log data. 


STATE_CHECK 


DEALLOC_FLUSH_BAD_STATE 


The program specified the 
TYPE(SYNC_LEVEL) parameter on a 
conversation specified with 
SYNC_LEVEL=NONE when the 
conversation was not in the send state. 
Alternatively, the program can cause this 
error by specifying TYPE(FLUSH) when the 
conversation is not in send state. 


Issue the verb in the correct state. 

DEALLOC_CONFIRM_BAD STATE 

The program specified the 
TYPE(SYNC_LEVEL) parameter on a 
conversation specified with 
SYNC_LEVEL=CONFIRM when the 
conversation was not in send state. 
Issue the verb in the correct state. 


DEALLOC_NOT_LL_BDY 
The program specified the TYPE(FLUSH) 


or the TYPE(SYNC_LEVEL) parameter, 


the conversation is in send state, and the 
program started but did not finish sending a 
logical record. 


Action: Finish sending the logical record. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e X’0003’ ALLOCATION_ERROR 

e X’F003’ APPC_ABENDED 

e X’F002’ APPC_BUSY 

e X’F001’ APPC_DISABLED 

e X’0010’ CONV_FAILURE_NO_RETRY 

e X’000F’ CONV_FAILURE_RETRY 

e X’0019’ CONVERSATION_TYPE_MIXED 
e X’0005’ DEALLOCATE_ABEND 

e X’0006’ DEALLOCATE_ABEND_PROG 

e X’0007’ DEALLOCATE_ABEND_SVC 

e X’0008’ DEALLOCATE_ABEND_ TIMER 
e X’F004’ INCOMPLETE 

e X’F005’ INCOMPLETE_ALTERED VERB 
e X’0000’ OK 

e X’000E’ PROG_ERROR_PURGING 

e X’0013’ SVC_ERROR_PURGING. 
DETACH_LU 


e X’00000003’ BAD _LU_ID 
Description: APPC/PC does not recognize the specified 
LU_ID. 
Action: Match this LU_ID with the one APPC/PC 
returns after executing the ATTACH_LU verb. 
e X’00000223’ SSCP_CONNECTED_ LU 
Description: The program can issue DETACH_LU only for 
independent LUs that do not have active 
sessions with the SSCP. 
Action: Use the DETACH_PU verb to reset the node. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e X’F0030000’ APPC_ABENDED 


e X’F0020000’ APPC_BUSY 
@ X’F0010000’ APPC_DISABLED 
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X’00000000’ OK. 


DETACH_PU 


X’00000008’ NO_PU_ATTACHED 


Description: The application subsystem has not yet issued 
ATTACH_PU to define the PU being detached. 


Action: Issue an ATTACH PU verb. 
X’00000272’ ADAPTER CLOSE FAILURE 


Description: APPC/PC has experienced a failure while 
trying to close an adapter. 


Action: Check the SYSLOG entry for possible adapter 
problem indications. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F0030000’ APPC_ABENDED 
X’F0020000’ APPC_BUSY 

X’F 0010000’ APPC_DISABLED 
X’00000000’ OK. 


DISABLE/ENABLE_APPC 


The DISABLE/ENABLE_APPC verb does not provide a 
RETURN_CODE parameter. 


DISPLAY 


X’00000003’ BAD_LU_ID 


Description: APPC/PC does not recognize the specified 
LU_ID. 


Action: Match this LU_ID with the one APPC/PC 
returns after executing the ATTACH _LU verb. 


C-34 


e X’000001B1’ BAD_PART_LUNAME 


Description: APPC/PC does not recognize the supplied 
PARTNER _ LU NAME parameter value. 


Action: Match the PARTNER LU_NAME with the 
PARTNER _LU_NAME specified with the 
ATTACH_LU verb. 


e X’000001B2’ BAD_MODENAME 


Description: APPC/PC does not recognize the 
MODE_NAME parameter value. 


Action: Match the MODE_NAME with the 
MODE_NAME specified with the 
ATTACH _ LU_ verb. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 0030000’ APPC_ABENDED 
X’F0020000’ APPC_BUSY 
X’F0010000’ APPC_DISABLED 
X’00000000’ OK. 


FLUSH and MC_FLUSH 
e X’0001’ PARAMETER_CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


C-35 


Action: Check the CONV_ID parameter for validity. 
e X’0002’ STATE CHECK 
— X’00000061’ FLUSH _NOT_SEND_ STATE 


Description: The conversation must be in send state to 
flush the local LU’s send buffer. 


Action: Issue the verb in send state. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’FO0O’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_MIXED 
X’0000’ OK. 


GET_ALLOCATE 
e X’00000003’ BAD_LU_ID 


Description: APPC/PC does not recognize the specified 
LU_ID. 


Action: Match this LU_ID with the one APPC/PC 
returns after executing the ATTACH LU verb. 


e X’00000281’ GET_ALLOC_BAD_ TYPE 


Description: APPC/PC does not recognize the parameter 
specified in the TYPE field. 


Action: Check the TYPE field. The TYPE should be 
X’00’ for DEQUEUVE or X’01’ for TEST. 


e X’00000282’ UNSUCCESSFUL 


Description: The LU is not currently holding any incoming 
ALLOCATEs in the queue. 


Action: This is not an error indication. 
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For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. . 


X’F 0030000’ APPC_ABENDED 
X’F0020000’ APPC_BUSY 
X’F0010000’ APPC_DISABLED 
X’00000000’ OK. 


GET_ATTRIBUTES and MC_GET_ATTRIBUTES 
e X’0001’ PARAMETER_CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP_STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


— X/’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY — 

X’F001’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_MIXED 
X’0000’ OK. 
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GET_TYPE 
e X’0001’ PARAMETER _ CHECK 
— ‘00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP_STARTED verb for a locally initiated 
TP or the CREATE _ TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e@ X’F003’ APPC_ABENDED 
e X’F002’ APPC_BUSY 

e X’F001’ APPC_DISABLED 
e X’0000’ OK. 
PASSTHROUGH 


The PASSTHROUGH verb does not provide a RETURN_CODE 
parameter. 
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POST_ON_RECEIPT 


e X’0001’ 


e X’0002’ 


X’00000001’ 


Description: 


Action: 


X’00000002’ 


Description: 


Action: 
X’00000091’ 


Description: 


Action: 


X’00000093’ 


Description: 


Action: 


X’00000092’ 
Description: 


Action: 


PARAMETER_CHECK 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 

TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


BAD_CONV_ID 


APPC/PC does not recognize the specified 
CONV_ID. 


Check the CONV_ID parameter for validity. 
INVALID_LENGTH 


The program specified an illegal] value for 
the MAX LENGTH parameter. 


Specify a length in the range 0 to 32767 
inclusive. 


P_ON_R_BAD_ FILL 


The program specified an illegal value for 
the FILL parameter. 


Check the FILL field. The only valid values 
are X’00’ for BUFFER and X’01’ for LL. 


STATE_CHECK 


P_ ON _R_NOT_RCV_STATE 
The conversation is not in receive state. 


Issue the verb in receive state. 
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e X’0019’ 


CONVERSATION_TYPE_MIXED 


Description: The program issued the verb on a mapped 


Action: 


conversation. 


Issue the verb only on a basic conversation. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 003’ 
X’F002’ 
X’FO01’ 
X’0000’ 


APPC_ABENDED 
APPC_BUSY 
APPC_DISABLED 
OK. 


PREPARE_TO_RECEIVE and 
MC_PREPARE_TO_RECEIVE 


e X’0001’ 
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PARAMETER_CHECK 


X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 


Action: 


TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP_STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 
Action: Check the CONV_ID parameter for validity. 


X’000000A1’ P_TO_R_INVALID_TYPE 


Description: APPC/PC does not recognize the specified 
TYPE. 
Action: Check the TYPE field. The only valid 


values are X’00’ for SYNC_LEVEL and 
X’01’ for FLUSH. 


X’0002’ STATE CHECK 


X’000000A2’ UNFINISHED _ LL 

Description: The conversation is in send state, and the 
program started, but did not finish, sending 
a logical record. 

Action: Finish sending the logical record. 

X’000000A3’ P_TO_R_ NOT _SEND_ STATE 


Description: The conversation is not in send state. 


Action: Issue the verb in send state. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0003’ ALLOCATION_ERROR 

X’F 003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’F001’ APPC_DISABLED 

X’0019’ CONVERSATION _TYPE_MIXED 
X’0010’ CONV_FAILURE_NO_RETRY 
X’000F” CONV_FAILURE_RETRY 
X’0005’ DEALLOCATE_ABEND 

X’0006’ DEALLOCATE_ABEND_ PROG 
X’0007’ DEALLOCATE_ABEND_SVC 
X’0008’ DEALLOCATE_ABEND_TIMER 
X’F004’ INCOMPLETE 

X’F005’ INCOMPLETE_ALTERED_VERB 
X’0000’ OK 

X’000K’ PROG_ERROR_PURGING 
X’0013’ SVC_ERROR_PURGING. 


RECEIVE_AND_WAIT and MC_RECEIVE_AND_WAIT 


X’0001’ PARAMETER _ CHECK 


X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 
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Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 
— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
— X’00000006’ DATA AREA ACROSS_ SEGMENT 


Description: The receive data area crosses a segment 
boundary. 


Action: Make sure the offset of the LOG_ DATA 
address plus the LOG_DATA_ LENGTH 
does not exceed 65535. 
— X’000000B5’ RCV_AND_ WAIT BAD_ FILL 


Description: The program specified an illegal value for 
the FILL parameter. 


Action: Check the FILL field. The only valid values 
are X’00’ for BUFFER and X’01’ for LL. 


@ X’0002’ STATE CHECK 
— X’000000B1’ RCV_AND_WAIT_BAD_STATE 


Description: The conversation is not in send or receive 
state. 


Action: Issue the verb only in send or receive state. 

— X’000000B2’ RCV_AND_ WAIT _NOT_LL_BDY 
Description: The conversation is in send state, and the 
program started, but did not finish, sending 


a logical record. 


Action: Finish sending the logical record. 
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For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0000’ OK 


X’0003’ ALLOCATION_ERROR 

X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’F001’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_ MIXED 
X’0010’ CONV_FAILURE_NO_ RETRY 
X’000F” CONV_FAILURE_RETRY 
X’0005’ DEALLOCATE_ABEND 

X’0006’ DEALLOCATE_ABEND_PROG 
X’0007’ DEALLOCATE_ABEND_SVC 
X’0008’ DEALLOCATE_ABEND_TIMER 
X’0009’ DEALLOCATE_NORMAL 
X’F004’ INCOMPLETE 

X’F005’ INCOMPLETE_ALTERED_VERB 


X’000C’ PROG_ERROR_NO_TRUNC 
X’000E’ PROG_ERROR_PURGING 
X’000D’ PROG_ERROR_TRUNC 
X’0011’ SVC_ERROR_NO_TRUNC 
X’0013’ SVC_ERROR_PURGING 
X’0012’ SVC_ERROR_TRUNC. 


RECEIVE_IMMEDIATE and MC_RECEIVE_ IMMEDIATE 


e X’0001’ PARAMETER CHECK 


— X’00000001’ 


Description: 


Action: 


— X’00000002’ 


Description: 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 

TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


BAD_CONV_ID 


APPC/PC does not recognize the specified 


‘ CONV_ID. 


Action: 


Check the CONV_ID parameter for validity. 
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— X’00000006’ DATA AREA ACROSS SEGMENT 
Description: The data area crosses a segment boundary. 
Action: Make sure the offset of the LOG_DATA 

address plus the LOG_DATA_ LENGTH 
does not exceed 65535. 
— X’000000C4’ RCV_IMMD BAD FILL 


Description: The program specified an illegal value for 
the FILL parameter. 


Action: Check the FILL field. The only valid values 
are X’00’ for BUFFER and X’01’ for LL. 


X’0002’ STATE _CHECK 

— X’000000C1’ RCV_IMMD_NOT_RCV_STATE 
Description: The conversation is not in receive state. 
Action: Issue the verb in receive state. 

X’0014’ UNSUCCESSFUL 

Description: There is nothing to receive. 


Action: This return code is not an error indication. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0003’ + ~=ALLOCATION_ERROR 

X’F003’ + =APPC_ABENDED 

X’F002’ =APPC_BUSY 

X’F001! = APPC_DISABLED 

X’0019 ++=CONVERSATION_TYPE_MIXED 
X’0010° = CONV_FAILURE_NO_RETRY 
X’000F’ CONV_FAILURE_RETRY 
X’0005° +=DEALLOCATE_ABEND 

X’0006’ +=DEALLOCATE_ABEND PROG 
X’00077 +~=DEALLOCATE_ABEND_SVC 
X’0008 += DEALLOCATE ABEND TIMER 
X’0009 § DEALLOCATE_NORMAL 
X’F004" INCOMPLETE 

X’F005° INCOMPLETE_ALTERED_VERB 
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X’0000’ OK 

X’000C’ PROG_ERROR_NO_TRUNC 
X’000E’ PROG_ERROR_PURGING 
X’000D’ PROG_ERROR_TRUNC 
X’0011’ SVC_ERROR_NO_TRUNC 
X’0013’ SVC_ERROR_PURGING 
X’0012’ SVC_ERROR_TRUNC. 


REQUEST_TO_SEND and MC_REQUEST_TO_SEND 
e X’0001’ PARAMETER _ CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
e X’0002’ STATE CHECK 
— X’000000E1’ R_T_S_ NOT_RCV_STATE 


Description: The conversation is not in receive or 
confirm state. 


Action: Do not issue REQUEST_TO_SEND in send 
state. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e X’F003’ APPC_ABENDED 


e X’F002’ APPC_BUSY 
e X’FO01’ APPC_DISABLED 
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e X’0019’ 


e X’0000’ OK. 


CONVERSATION_TYPE_MIXED 


SEND_DATA and MC_SEND_DATA 


e X’0001’ 
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X’00000001’ 


Description: 


Action: 


X’00000002’ 


Description: 


Action: 
X’00000006’ 


Description: 


Action: 


X’000000F 1’ 


Description: 


Action: 


PARAMETER_CHECK 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 

TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


BAD_CONV_ID 


APPC/PC does not recognize the specified 
CONV_ID. 


Check the CONV_ID parameter for validity. 
DATA _AREA ACROSS_SEGMENT 


The send data area crosses a segment 
boundary. 


Make sure the offset of the LOG _ DATA 
address plus the LOG_DATA LENGTH 
does not exceed 65535. 


BAD_LL 
DATA contains an invalid logical record 
length (LL) value of hex 0000, 0001, 8000, or 
8001. 


Check the logical record length and the LL 
field. 


e X’0002’ STATE_CHECK 
— X’000000F2’ SEND_DATA_NOT_SEND_STATE 
Description: The conversation is not in send state. 
Action: Issue the verb in send state. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0003’ ALLOCATION_ERROR 

X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’FO0I’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_ MIXED 
X’0010’ CONV_FAILURE_NO_ RETRY 
X’000F” CONV_FAILURE_RETRY 
X’0005’ DEALLOCATE_ABEND 

X’0006’ DEALLOCATE_ABEND_PROG 
X’0007’ DEALLOCATE_ABEND_SVC 
X’0008’ DEALLOCATE_ABEND_ TIMER 
X’0009’ DEALLOCATE_NORMAL 
X’F004’ INCOMPLETE 

X’F005’ INCOMPLETE_ALTERED_VERB 
X’0000’ OK 

X’000E’ PROG_ERROR_PURGING 
X’0013’ SVC_ERROR_PURGING. 


SEND_ERROR and MC_SEND_ERROR 
e X’0001’ PARAMETER_CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 


Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP_STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 
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— X’00000002’ 


Description: 


Action: 


— X’00000006’ 


Description: 


Action: 


— X’00000102’ 


Description: 


Action: 


— X’00000103’ 


Description: 


Action: 


BAD_CONV_ID 


APPC/PC does not recognize the specified 
CONV_ID. 


Check the CONV_ID parameter for validity. 
DATA AREA ACROSS_SEGMENT 


The log data area crosses a segment 
boundary. 


Make sure the offset of the LOG_ DATA 
address plus the LOG_ DATA LENGTH 
does not exceed 65535. 


LOG_LL_WRONG 


The LL field of the log data does not 
match the specified length. 


Check the length of the data and the LL 
field. 


BAD _ TYPE 


APPC/PC does not recognize the specified 
error TYPE. 


Check the value of the TYPE parameter. 
The valid values are PROG (X’00’) and SVC 
(X’01’). 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 
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X’0003’ ALLOCATION _ERROR 

X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’F001’ APPC_DISABLED 

X’0019’ CONVERSATION TYPE MIXED 
X’0010’ CONV_FAILURE_NO_RETRY 
X’000F” CONV_FAILURE_RETRY 
X’0005’ DEALLOCATE_ABEND 

X’0006’ DEALLOCATE_ABEND_ PROG 
X’0007’ DEALLOCATE_ABEND_ SVC 
X’0008’ DEALLOCATE_ABEND_TIMER 


X’0009" +=DEALLOCATE_NORMAL 

X’F004’ INCOMPLETE 

X’F005’ = INCOMPLETE_ALTERED_VERB 
X’0000° ~=s« OK | 

X’000E’ §PROG_ERROR_PURGING 
X’0013’ +~=SVC_ERROR_PURGING. 


SET_PASSTHROUGH 


The SET _PASSTHROUGH verb does not provide a 
RETURN_CODE parameter. 


TEST and MC_TEST 


X’0000’ OK 
— X’00000000’ POSTED_DATA 


Description: The LU has posted the connection and 
data is available in an LU’s receive buffer. 


Action: This return code does not indicate an error 
condition. 


— X’00000001’ POSTED_NOT_DATA 


Description: The LU has posted the conversation and 
information other than data is available in 
the LU’s receive buffer. This return code is 
not an error condition. 


Action: Issue RECEIVE_AND_ WAIT or 
RECEIVE_IMMEDIATE to receive the 
information. This return code is not an 
error notification. 

X’0001’ PARAMETER CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 
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Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE _ TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
e X’0002’ STATE CHECK 
X’00000122’ NOT _RCV_STATE 
Description: The conversation is not in receive state 
and the program specified the POSTED 
option for the TYPE parameter. 
Action: Issue the verb in receive state. 
e X’0014’ UNSUCCESSFUL 
Description: For TEST(POSTED), the conversation has not 
been posted. For TEST 
(REQUEST TO SEND RECEIVED), the 
REQUEST_TO_SEND indication has not been 
received. 
Action: Reissue the verb later. 


e X’000B’ POSTING_NOT_ACTIVE 


Description: Posting is not active for the specified 
conversations. 


Action: Issue POST_ON_ RECEIPT before testing the 
conversation. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


@ X’0003’ ALLOCATION ERROR 


e = X’F003’ APPC_ABENDED 
e X’F002’ APPC_BUSY 
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X’FO01’ 
X’0019’ 
X’0010’ 
X’000F” 
X’000A’ 
X’0005’ 
X’0006’ 
X’0007’ 
X’0008’ 
X’0009’ 
X’F004’ 
X’F 005’ 
X’000C’ 
X’000K’ 
X’000D’ 
X’0011’ 
X’0013’ 
X’0012’ 


TP_ENDED 


e X’00000001’ 


APPC_DISABLED 
CONVERSATION_TYPE_MIXED 
CONV_FAILURE_NO_RETRY 
CONV_FAILURE_RETRY 
DATA_POSTING_BLOCKED 
DEALLOCATE_ABEND 
DEALLOCATE_ABEND_PROG 
DEALLOCATE ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_ VERB 
PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


BAD_TP_ID 


Description: APPC/PC does not recognize the specified 


Action: 


TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP_STARTED verb for a locally initiated TP or 
the CREATE_TP record for a remotely initiated 
TP. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 0030000’ 
X’F 0020000’ 
X’F0010000’ 
X’F 0040000’ 
X’F0050000’ 
X’00000000’ 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 

INCOMPLETE 

INCOMPLETE ALTERED _VERB 
OK. 
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TP_STARTED 
e X’00000003’ 


Description: 


Action: 


e X’00000243’ 


Description: 


Action: 


BAD_LU_ID 


APPC/PC does not recognize the specified 
LU_ID. 


Match this LU_ID with the one APPC/PC 
returns after executing the ATTACH LU verb. 


TOO_MANY_TPS 


APPC/PC is already running the maximum 
number of transaction programs that this LU 
can run concurrently (as defined with the 
MAX_TPS parameter in the ATTACH LU 
verb). This return code indicates that the 
application subsystem cannot initiate the 
transaction program locally. The condition may 
be temporary if an incoming ALLOCATE was in 
the process of being rejected. 


Terminate other transaction programs to make 
room, or issue the CHANGE_LU verb to 
increase MAX _ TPS. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


e X’F0030000’ 
e X’F0020000’ 
e X’F0010000’ 
e X’00000000’ 
TP_VALID 


e X’00000001’ 


Description: 


Action: 
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APPC_ABENDED 
APPC_BUSY 
APPC_ DISABLED 
OK. 


BAD_TP_ID 


APPC/PC does not recognize the specified 
TP_ID. 


Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated TP or 


e X’00000002’ 


Description: 


Action: 
e X’00000110’ 


Description: 


Action: 


the CREATE_TP record for a remotely initiated 
TP. 


BAD_CONV_ID 


APPC/PC does not recognize the specified 
CONV_ID. 


Check the CONV_ID parameter for validity. 
BAD_STATE 


TP VALID does not follow a 
GET_ALLOCATE. 


Issue TP_VALID verb immediately after 
GET_ALLOCATE. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F 0030000’ 
X’F0020000’ 
X’F0010000’ 
X’F0040000’ 
X’F0050000’ 
X’00000000’ 


TRACE 


APPC_ABENDED 

APPC_BUSY 

APPC_DISABLED 

INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK. 


The TRACE verb does not provide a RETURN_CODE parameter. 


TRANSFER_MS_DATA 


e X’00000301’ 


Description: 


Action: 


SSCP_PU_SESSION_NOT_ACTIVE 


APPC/PC could not send the NMVT because 
the SSCP_ PU session was not active. 


Contact the host operator to activate an 
SSCP_PU session. 
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e X’00000302’ DATA EXCEEDS RU_ SIZE 
Description: The data exceeded the allowable RU size. 


Action: Reduce the size of data sent or check that the 
RU size is adequate. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’F0030000’ APPC_ABENDED 
X’F0020000’ APPC_BUSY 
X’F0010000’ APPC_DISABLED 
X’00000000’ OK. 


WAIT 
e X’0000’ OK 
— X’00000000’ POSTED_DATA 


Description: The LU has posted the conversation and 
data is available in an LU’s receive buffer. 


Action: This return code does not indicate an error 
condition. 


— X’00000001’ POSTED _NOT_DATA 
Description: The LU has posted the conversation and 
information other than data is available in 


the LU’s receive buffer. 


Action: Issue RECEIVE. AND_ WAIT or 
RECEIVE IMMEDIATE to receive the 
information. This return code is not an 
error notification. 


e X’0001’ PARAMETER _CHECK 
— X’00000001’ BAD_TP_ID 


Description: APPC/PC does not recognize the specified 
TP_ID. 
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Action: Match the TP_ID with the TP_ID that 
APPC/PC returns after executing the 
TP STARTED verb for a locally initiated 
TP or the CREATE_TP record for a 
remotely initiated TP. 


— X’00000002’ BAD_CONV_ID 


Description: APPC/PC does not recognize the specified 
CONV_ID. 


Action: Check the CONV_ID parameter for validity. 
e X’0002’ STATE CHECK 
— X00000122’ NOT_RCV_STATE 


Description: One of the conversations in the CONV_ID 
list is not in receive state (for 
TYPE =POSTED). 


Action: Check the TYPE field for accuracy. Issue 
verbs to place the conversation in receive 
state. 


e X’000B’ POSTING_NOT_ACTIVE 


Description: The program issued a WAIT verb before 
issuing POST_ON_RECEIPT verbs for any of 
the conversations included on the WAIT verb 
list. 


Action: The transaction program must issue a 
POST_ON_RECEIPT for at least one of the 
conversations on the WAIT verb list. 


For descriptions of the following return codes, see “Common 
Return Codes” on page C-2. 


X’0003 ALLOCATION_ERROR 

X’F003’ APPC_ABENDED 

X’F002’ APPC_BUSY 

X’F 001’ APPC_DISABLED 

X’0019’ CONVERSATION_TYPE_MIXED 
X’0010’ CONV_FAILURE_NO_RETRY 
X’000F” CONV_FAILURE_RETRY 
X’000A’ DATA_POSTING_BLOCKED 
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X’0006’ 
X’0007’ 
X’0008’ 
X’0009’ 
X’F004’ 
X’F005’ 
X’0000’ 
X’000C’ 
X’000K’ 
X’000D’ 
X’0011’ 
X’0013’ 
X’0012’ 
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DEALLOCATE_ABEND_PROG 
DEALLOCATE_ABEND_SVC 
DEALLOCATE_ABEND_TIMER 
DEALLOCATE_NORMAL 
INCOMPLETE 
INCOMPLETE_ALTERED_VERB 
OK 

PROG_ERROR_NO_TRUNC 
PROG_ERROR_PURGING 
PROG_ERROR_TRUNC 
SVC_ERROR_NO_TRUNC 
SVC_ERROR_PURGING 
SVC_ERROR_TRUNC. 


Appendix D. SYSLOG Type Codes 


This appendix lists the SYSLOG type codes. SYSLOG codes 
represent error conditions including data errors reported by the 
transaction program, link errors, configuration errors, and 
system protocol errors. If protocol errors persist, refer to 
Appendix I, “Statement of Service,” for information on obtaining 
program service. 


Some of the terminology below is not defined in this manual. See 
the SNA Format and Protocol Reference Manual, for unfamiliar 
terms. The asterisk (*) in the following tables indicates that the 
SYSLOG type code signals a protocol error. 


Type Subtype Meaning 


X’0001’ Sense code Conversation error 

generated from SEND_ERROR, 

MC_SEND_ERROR, 

DEALLOCATE 

(of an ABEND type), 

MC_DEALLOCATE 

(TYPE = ABEND). 

SYSLOG ADDITIONAL_INFO 

points to a byte containing 

one of the following: 
X’00’ - locally generated 
conversation error 
X’01’ - remotely generated 
conversation error 

If log data is present, SYSLOG 
DATA points to the data. 

If log data is not present, 
SYSLOG DATA is 
X’FFFFFFFF’. 

X’0002’ = Received an OAF-DAF address 
which duplicates one already 
active 

X’0003’ Cannot route request to LU 
(The LU may not be ATTACHed 
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Type 


X’0004’ 
X’0005’ 
X’0006’ 
X’0007’ 
X’0008’ 


X’0009’ 


X’000.A’ 
X’000B’ 
X’000C’ 
X’000D’ 
X’000E’ 
X’000F” 
X’0010’ 
X’0011’ 
X’0012’ 
X’0013’ 
X’0014’ 


X’0015’ 
X’0016’ 


X’0017’ 
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Subtype 


* 
* 


* 
* 


Sense Code * 


* 


* 


Sense code * 


* 


Meaning 


or the LU name or NAU 
address may be incorrect.) 
OAF-DAF address space filled 
(Too many sessions may be active.) 
Begin Bracket bit not set in RH 
Received an unexpected RTR 
Received an unexpected BIS reply 
Conversation-level protocol 
error detected at the 
basic conversation level. 
The session is deactivated 
with an UNBIND indicating 
a type X’FE’ protocol error. 
Conversation level protocol 
error detected for a mapped 
conversation. APPC/PC issues a 
DEALLOCATE TYPE(ABEND) 
for the conversation. 
Received a BIND response with no 
outstanding request 
NS header not recognized on 
an SSCP-LU or SSCP-PU session 
Received an UNBIND request 
with syntax error 
Received session control 
request with format error 
Received UNBIND response with no 
outstanding request 
Received INITSELF response with 
no outstanding request 
Received BIND request with syntax, 
state, or semantic error 
Received unexpected BIS request 
Received invalid NS record 
Session level protocol error detected 
Received frame from DLC in error 
Bracket error 
Received route inop - line has gone 
down (This is the only logged 
SDLC error.) See 
“SDLC Problems” on page D-22 . 
Network Management NMVT 
message (See “Network 
Management NMVT Message” 


Type 


X’0018’ 


X’0019’ 
X’001A’ 
X’001B’ 


Subtype 


X’00000000’ 
X’00000001’ 


X’00000002’ 
X’00000003’ 
* 


X’00000101’ 
X’00000102’ 
X’00000103’ 
X’00000105’ 
X’00000106’ 
X’00000107’ 


X’00000108’ 


X’00000200’ 
X’00000300’ 
X’00000400’ 
X’00000500’ 
X’00000600’ 
X’00000700’ 
X’00000800’ 
X’8xxxxxxx’ 


Meaning 


in this appendix.) 
User-defined data 
A complete NMVT (NS header, 
major vector, and appropriate 
subvectors) 
TRANSFER ALERT 
TRANSFER_PDSTATS 
Received Error Data GDS Variable 
from a partner on a mapped 
conversation. APPC/PC issues 
a DEALLOCATE(ABEND) 
for the conversation 
Session Level Security Error 
Conversation Level Security Error 
Link Level Error (See IBM 
Token-Ring Network Problems 
on page D-5 and IBM 
Token-Ring Network Problem 
Determination Guide ) 
Invalid adapter 
Command not recognized 
Invalid link ID 
Invalid parameter table 
Required parameter missing 
Invalid Parameter Table 
field 
Invalid number of 
connections 
Adapter not open 
Duplicate command 
Remote station not responding 
DLC unsuccessful—retry 
DLC unsuccessful—no retry 
XID protocol error 
Connection failure 
DLC-specific link level error 
(A 1 must appear in left-most bit; 
the meaning of each code is 
determined by the 
particular DLC.) 
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Note: 


For link level errors, SYSLOG ADDITIONAL _INFO points to 
a DLC address of up to 26 characters, in the same format as 
in the ATTACH _LU verb. 


Type Subtype Meaning 

X’001C’ NMVT message too large for the 
RU size 

X’001D’ * Received non-normal UNBIND 


(Due to a protocol error or a 
DETACH _PU(HARD) verb) 


The subcodes below refer to the UNBIND type: 


Type Subtype Meaning 
X’00000003’ Session outage 
X’00000006’ Invalid parameters 
X’00000007’ Virtual route map 
X’00000008’ Route extension INOP 
X’00000009’ Hierarchical reset 
X’0000000A’ SSCP gone 
X’0000000B’ Virtual route deactivated 
X’0000000C’ Unrecoverable LU failure 
X’0000000E’ Recoverable LU failure 
X’0000000F’ Cleanup 
X’00000011’ Gateway node cleanup 
X’000000F E’ Protocol violation 

Note: 


Type 
X’FFFF’ 
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For abnormal UNBIND errors, SYSLOG ADDITIONAL-INFO 
points to the 17 character fully qualified partner LU name, 
followed by the 8-character mode name. 

Subtype Meaning 


abnormal termination 
of APPC/PC 


The abnormal termination subtypes below indicate either an 
invalid configuration file or an APPC/PC program error. 
Restore or reconstruct the configuration file from the 
APPC/PC menus, if possible, to correct these problems. (For 


information on the APPC/PC menus refer to the APPC/PC 
Installation and Configuration Guide.) 


Type Subtype Meaning 


X’00000000’ No available storage, APPC/PC will 
try to close adapters. 

X’00000001’ No available storage, APPC/PC 
cannot continue. If the IBM 
Token-Ring Network is left 
in an unstable state, the 
keyboard may be locked. The 
SYSLOG exit routine can 
choose to unlock the keyboard 
and not return to APPC/PC. 


X’00000002’ Process being created is unknown. 
X’00000003’ Process fell through to its end. 
X’00000004’ Sending to a nonexistent queue. 
X’00000005’ Receiving from a nonexistent queue. 


X’00000006’ * Invalid variant variable in 
configuration file. 


* These SYSLOG type codes indicate protocol errors. 


IBM Token-Ring Network 
Problems 


APPC/PC reports failures on the IBM Token-Ring Network and 
the adapter using its SYSLOG facilities. APPC/PC uses two 
SYSLOG TYPE codes for these data-link-level errors. A SYSLOG 
of type LINK ERROR (X’001B’) indicates that either the IBM 
Token-Ring Network adapter or the component of APPC/PC that 
interfaces to the adapter has determined that it is unable to 
complete a command. A SYSLOG of type Network Management 
NMVT Message (X’0017’) indicates the loss or impending loss of 
an adapter or a network resource. 


Link-Level Errors 


The SUBTYPE and ADDITIONAL _INFO fields of the SYSLOG 
record return information for link level errors. 
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Understanding Link Error Subtypes 


The link error subtype identifies the specific link-level error that 
occurred. 


The following list of link error subtypes describes the causes of 
these errors and provides recommended solutions. 
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X’00000101’ Invalid Adapter 


Description: APPC/PC tried to issue a command to the 
IBM Token-Ring Network containing an 
adapter ID which is not X’00’ or X’01’. 


Action: Verify that the definition of Partner LUs on the 
ATTACH _LU verb specifies only adapter ID 
values X’00’ or X’01’. 


X’00000102’ Command Not Recognized 


Description: An unexpected internal APPC/PC software 
error occurred. 


Action: Refer to Appendix I, “Statement of Service,” 
for information on obtaining program service. 


X’00000103’ Invalid Link ID 


Description: APPC/PC Invalidly issued commands for an 
IBM Token-Ring Network link which was in the 
process of being disconnected, or after an 
unrecoverable software error occurred. 


Action: ALLOCATE a conversation as necessary to 
establish the link. If the error persists, refer to 
Appendix I, “Statement of Service,” for 
information on obtaining program service. 


X’00000105’ Invalid Parameter Table 


Description: An unexpected internal APPC/PC software 
error occurred. 


Action: Refer to Appendix I, “Statement of Service,” 
for information on obtaining service. 


X’00000106’ Required Parameter Missing 


Description: An unexpected internal software error 
occurred. 


Action: Refer to Appendix I, “Statement of Service,” 
for information on obtaining program service. 


X’00000107’ Invalid Parameter Table Field 


Description: The IBM Token-Ring Network adapter found 
an invalid value for a parameter table field. 


Action: If the error occurred during processing of the 
ACTIVATE DLC verb, verify that the adapter 
address specified in your APPC/PC 
configuration is valid (that is, the high order bit 
in this address is not set). 


X’00000108’ Invalid Number of Connections 


Description: The number of incoming link connections 
calculated was greater than the maximum 
number of link stations. 


Action: _ Retry the ACTIVATE _DLC verb. If the error 
persists, refer to Appendix I, “Statement of 
Service,” for information on obtaining program 
service. 


X’00000200’ Adapter Not Open 


Description: The program issued commands to an IBM 
Token-Ring Network adapter that the ~ 
application subsystem has not opened. 


Action: Issue the ACTIVATE DLC verb to open the 
adapter. 


X’00000300’ Duplicate Command 
Description: The program issued two ACTIVATE DLC 
verbs for the same IBM Token-Ring Network 


adapter, or an unexpected software error 
occurred. 
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Action: Verify that the program is not issuing two 
ACTIVATE DLC verbs for the same adapter. If 
this action does not solve the problem, refer to 
Appendix I, “Statement of Service” for 
information on obtaining program service. 


X’00000400’ Remote Station Not Responding 


Description: IBM Token-Ring Network adapter received no 
response on the network when attempting to 
locate a partner node. 


Action: Verify that the specification of the adapter 
address of the partner node is correct and that 
the node is operational on the network (that is, 
its adapter has been open and initialized). 


X’00000500’ DLC Unsuccessful—Retry 


Description: The IBM Token-Ring Network adapter 
detected a sequence error. 


Action: Retry the conversation that failed. 
X’00000600’ DLC Unsuccessful—No Retry 


Description: A catastrophic, unrecoverable failure 
occurred. 


Action: The application subsystem must reopen the 
adapter that failed by issuing the 
ACTIVATE _ DLC verb. 


X’00000700’ XID Protocol Error 


Description: An unexpected XID was received during the 
XID exchange process on the IBM Token-Ring 
Network link. 


Action: If error persists refer to Appendix I, “Statement 
of Service,” for information on obtaining 
program service. 


e X’00000800’ Connection Failure 
Description: The IBM Token-Ring Network link that 
previously existed with a partner node has been 
unexpectedly disconnected. 


Action: Check that the partner node has not 
deliberately disconnected. 


Understanding Link Error Data 

In addition to a subtype code, the link error specifies an 

ADDITIONAL _INFO pointer. This pointer indicates the location 

of the following information: 

DLC NAME: ’ITRN  ’” (8 ASCII characters) 

ADAPTER NUMBER: X’00’ if the error occurred on the primary 
adapter and X’01’ if the error occurred on the 
secondary adapter. 

DESTINATION ADDRESS: length (one byte) 

DESTINATION ADDRESS: Token-Ring Network address of the 
partner node as defined in the ATTACH _LU verb. 


Not applicable on all link errors. (up to 16-byte hex 
address) 


Network Management NMVT 
Messages 


The following fields of the SYSLOG record contain information 
for Network Management NMVT messages: 


SUBTYPE Specifies the NMVT message: 
X’00000000’ = USER DATA 
X’00000002’ = ALERT 


DATA Provides a Network Management vector. 


D-9 


ALERTS 


In addition to logging ALERTS locally, APPC/PC also sends the 
ALERT vector to an application program residing in the host 
computer if there is an active host SSCP-PU session when 
APPC/PC reports the ALERT. The application program displays 
information about the failure condition to an operator console. 


The ALERT Network Management vector is composed of the 
ALERT Major Vector, the Correlator Subvector, the Product Set 
ID Subvector, the Basic Alert Subvector, and a variable number 
of Hexadecimal Detail Qualifier Subvectors. 


The values for the Basic Alert Subvector and Hexadecimal Detail 
Qualifier Subvectors are unique to the type of error APPC/PC 
reports. The error categories that this section describes are: 


Adapter bring-up errors 
Adapter open errors 
Adapter check 

Ring status 

Ring status-remove received 
PC-detected 

Software errors. 


It is beyond the scope of this document to describe the subvector 
formats in detail. Consult the SNA Reference Summary for a 
complete description of the structure and format of the ALERT 
Major Vector and the associated subvectors. Consult the JBM 
Token-Ring Network PC Adapter Technical Reference Manual for 
a description of the specific adapter errors contained in the 
Hexadecimal Detail Qualifier Subvectors. 


In the following format descriptions, h represents a hexidecimal 

digit. 

Adapter Bring-Up Errors 

Description: Bring-up errors occur when the ACTIVATE DLC 
verb cannot initialize the IBM Token-Ring Network 


adapter successfully. These errors indicate that the 
adapter has failed a hardware diagnostic test. 
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Action: Run the IBM Token-Ring Network adapter 
diagnostics as described in the manual JBM 
Token-Ring Network PC Adapter Guide to 
Operations. 


For bring up errors, the ALERT subvectors are: 


Basic Alert Subvector 


e Subvector Length X’0D’ 

e Subvector Key X’91’ 

e Flags X’00’ Not operator 
initiated 

e Alert Type X’01’ Permanent error 

e General Cause Code X’01’ Hardware or 
microcode 


e Specific Component Code X’0012’ Communication 
link adapter 

e Alert Description Code X’0040’ 

e User Action Code X’0040’ 

e Detail Text Ref Code X’0040’ 


Hexadecimal Detail Qualifier 


e Subvector Length X’04’ 
e Subvector Key X’Al’ 
e Qualifier Data X’hhhh’ Adapter bring- 


up error code 


Hexadecimal Detail Qualifier 


e Subvector Length X’03’ 
e Subvector Key X’Al’ 
e Qualifier Data X’hh’ Adapter (0 | 1) 


EBCDIC Qualifier 


e Subector Length X’04’ 

e Subvector Key X’A0’ Type = qualifying 
data (hex) 

e Qualifier Data X’4040’ Null field = 
NPDA screen 
filler 


Hex Qualifier 


e Subector Length X’12’ 
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e Subvector Key X’Al’ Type = qualifying 
data (hex) 
@ Qualifier Data 6X’hh’ Adapter node 
address 
10X’hh’ Microcode EC 
level (10 
bytes) 


Adapter Open Errors 
Description: The ACTIVATE _DLC verb has failed to open the 
IBM Token-Ring Network adapter. The adapter 


could not successfully enter itself into the network. 


Action: Perform IBM Token-Ring Network problem 
determination procedures. 


For open errors, the ALERT subvectors are: 


Basic Alert Subvector 


e Subvector Length X’0D’ 

e Subvector Key X’91’ 

e Flags X’00’ Not operator 
initiated 

e Alert Type X01’ Permanent error 

e General Cause Code X’0B’ Hardware 

e Specific Component Code X’0080’ Token-Ring 
adapter 

e Alert Description Code X’0041’ 

e User Action Code X’0041’ 

e Detail Text Ref Code X’0041’ 

Hexadecimal Detail Qualifier 

e Subvector Length X’04’ 

e Subvector Key X’AT’ 

e Qualifier Data X’00hh’ 

Hexadecimal! Detail Qualifier 

e Subvector Length X’03’ 

e Subvector Key X’Al’ 

® Qualifier Data X’hh’ Adapter (0 | 1) 
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EBCDIC Qualifier 


e Subvector Length X’04’ 

e Subvector Key X’A0’ Type = qualifying 
data (hex) 

e Qualifier Data X’4040’ Null field = 
NPDA screen 
filler 

Hex Qualifier 

e Subvector Length X/12’ 

e Subvector Key X’ Al’ Type = qualifying 
data (hex) 

e Qualifier Data 6X’hh’ Adapter node 
address 

10X’hh’ Microcode EC 
level (10 
bytes) 


Adapter Check 


Description: The IBM Token-Ring Network Adapter has failed 
during operation. 


Action: Perform IBM Token-Ring Network problem 
determination procedures. 


For adapter check errors, the ALERT subvectors are: 


Basic Alert Subvector 


e Subvector Length X’0D’ 

e Subvector Key X’91’ 

e Flags X’00’ Not operator 
initiated 

e Alert Type X’01’ Permanent error 

e General Cause Code X’01’ Hardware or 
microcode 

e Specific Component Code X’0012’ Communications 
Link Adapter 

e Alert Description Code X’0042’ 

e User Action Code X’0040’ 

e Detail Text Ref Code X’0042’ 
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Hexadecimal] Detail Qualifier 


e Subvector Length X’0A’ 

e Subvector Key X’Al’ 

e Qualifier Data X’hhhh’ Adapter check 
error code 

6X’hh’ Adapter check 
parms 0-2 

Hexadecimal Detail Qualifier 

e Subvector Length X’03’ 

e Subvector Key X’Al’ 

e Qualifier Data X’hh’ Adapter (0 | 1) 

EBCDIC Qualifier 

e Subvector Length X’04’ 

e Subvector Key X’A0’ Type = qualifying 
data (hex) 

e Qualifier Data X’4040’ Null field = 
NPDA screen 
filler 

Hex Qualifier 

e Subvector Length X’12’ 

e Subvector Key X’Al’ Type = qualifying 
data (hex) 

e Qualifier Data 6X’hh’ Adapter node 
address 

10X’hh’ Microcode EC 
level (10 
bytes) 


Ring Status 


Description: The IBM Token-Ring Network adapter has 
encountered a token-ring failure condition. If the 
failure was the fault of the adapter, the token ring 
can recover without intervention. 


Action: Perform IBM Token-Ring Network problem 
determination procedures. 
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For ring status errors, the ALERT subvectors are: 


Basic Alert Subvector 


Hexadecimal Detail Qualifier 


Hexadecimal Detail Qualifier 


Subvector Length 
Subvector Key 
Flags 

Alert Type 


General Cause Code 


Specific Component Code 


Alert Description Code 


User Action Code 
Detail Text Ref Code 


Subvector Length 
Subvector Key 
Qualifier Data 


Subvector Length 
Subvector Key 
Qualifier Data 


EBCDIC Qualifier 


Subvector Length 
Subvector Key 


Qualifier Data 


Hex Qualifier 


Subvector Length 
Subvector Key 


Qualifier Data 


X’0D’ 
X’91’ 
X’00’ 
X’01’ 
X’0B’ 
X’0080’ 
X’0043’ 


X’0041’ 
X’0043 


X’04’ 
X’Al’ 
X’hhhh’ 


X’03’ 
X’Al’ 
X’hh’ 


X04’ 
X’A0’ 


X’4040’ 


X12’ 
X’AI’ 


6X’hh’ 


Not operator 
initiated 
Permanent 
error 
Hardware or 
microcode 
Token-Ring 
Network error 


Ring status 
code 


Adapter (0 | 1) 


Type = qualifying 
data (hex) 

Null field = 
NPDA screen 
filler’ 


Type = qualifying 
data (hex) 

Adapter node 
address 
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10X’hh’ Microcode EC 
level (10 
bytes) 


Ring Status - Remove Received 

Description: Another network entity forced the IBM 
Token-Ring Network adapter to remove itself from 
the network. 

Action: If this problem occurs repeatedly, refer to 
Appendix I, “Statement of Service,” for 


information on obtaining program service. 


For ring status-remove received errors, the ALERT subvectors 
are: 


Basic Alert Subvector 


e Subvector Length X’0D’ 

e Subvector Key X’91’ 

e Flags X’00’ Not operator 
initiated 

e Alert Type X’01’ Permanent error 

e General Cause Code X’0F’ Undetermined 

e Specific Component Code X’00FF’ Undetermined 

e Alert Description Code X’0044’ 

e User Action Code X’0044’ 

e Detail Text Ref Code X’0044’ 


Hexadecimal Detail Qualifier 


e Subvector Length X’04’ 

e Subvector Key X’Al’ 

e Qualifier Data X’hhhh’ Ring status 
code 

Hexadecimal Detail Qualifier 

e Subvector Length X’03’ 

e Subvector Key X’Al’ 

e Qualifier Data X’hh’ Adapter (0 | 1) 


EBCDIC Qualifier 


e Subvector Length X’04’ 
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Subvector Key 


Qualifier Data 


Hex Qualifier 


e Subvector Length 

e Subvector Key 

e Qualifier Data 
PC-Detected 


X’A0’ 


X’4040’ 


X’12’ 
X’AI’ 


6X’hh’ 
10X"hh’ 


Type = qualifying 
data (hex) 

Null field = 
NPDA screen 
filler 


Type = qualifying 
data (hex) 
Adapter node 
address 
Microcode EC 
level (10 
bytes) 


Description: The IBM Token-Ring Network adapter detected 


Action: 


an internal error. 


Reboot the program if possible; if the error persists, 


refer to Appendix I, “Statement of Service,” for 
information on obtaining program service. 


For PC-detected errors, the ALERT subvectors are: 


Basic Alert Subvector 


Subvector Length 
Subvector Key 
Flags 


Alert Type 
General Cause Code 


Specific Component Code 
Alert Description Code 


User Action Code 
Detail Text Ref Code 


Hexadecimal Detail Qualifier 


Subvector Length 


X’0D’ 
X’91’ 
X00’ 
X’01’ 
X’01’ 
X’0012’ 
X’0045’ 


X’0045’ 
X’0045’ 


X’04’ 


Not operator 
initiated 
Permanent error 
Hardware or 
microcode 
Communication 
link adapter 
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Hexadecimal Detail Qualifier 


EBCDIC Detail Qualifier 


Hexadecimal Detail Qualifier 
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Subvector Key 
Qualifier Data 


Subvector Length 
Subvector Key 
Qualifier Data 


Subvector Length 
Subvector Key 
Qualifier Data 


Subvector Length 
Subvector Key 
Qualifier Data 


Qualifier Data 


X’AI’ 
X’hhhh’ 


X’03’ 
X’Al’ 
X’hh’ 


X’04’ 
X’A0’ 
X’4040’ 


X12’ 
X’Al’ 
6X’hh’ 


10X’hh’ 


Ring status 
code 


Adapter (0 | 1) 


Null Field 


Adapter node 
address 

Microcode EC 
level (10 
bytes) 


Software Errors 


Description: The IBM Token-Ring Network data link control 
software detected an internal error. 


Action: Reboot the program if possible; if the error persists, 
refer to Appendix I, “Statement of Service,” for 
information on obtaining program service. 


For software errors, the ALERT subvectors are: 


Basic Alert Subvector 


e Subvector Length 
e Subvector Key 
e Flags 


e Alert Type 
e General Cause Code 


Specific Component Code 
Alert Description Code 
User Action Code 

Detail Text Ref Code 


Hexadecimal Detail Qualifier 


e Subvector Length 
e Subvector Key 
e Qualifier Data 


Hexadecimal Detail Qualifier 


e Subvector Length 
e Subvector Key 
e Qualifier Data 


EBCDIC Detail Qualifier 
e Subvector Length 


e Subvector Key 
® Qualifier Data 


X’0D’ 
X’91’ 
X00’ 


X01’ 
X18’ 


X’00FF’ 
X’0046’ 
X’0046’ 
X’0046’ 


X’04’ 
X’AI’ 
X’hhhh’ 


X’03’ 
X’AI’ 
X’hh’ 


X’04’ 
X’A0’ 
X’4040’ 


Not operator 
initiated 
Permanent error 
Microcode or 
software 
Undetermined 


Contents of IP 
register at 
detection 


Adapter (0 | 1) 


Null Field 
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Hexadecimal Detail Qualifier 


e Subvector Length X’12’ 

e Subvector Key X’Al’ 

e Qualifier Data 6X’hh’ Adapter node 
address 

e Qualifier Data 10X’hh’ Microcode EC 
level 

Hexadecimal Detail Qualifier 

e Subvector Length X’10’ 

e Subvector Key X’Al’ 

e Qualifier Data X’hhhh’ APPC/PC 
software error 
code 


X’hhhh’ Contents of 
register ES 
X’hhhh’ Contents of 
register BX 
X’hhhh’ Contents of 
register SI 
X’hhhh’ Contents of 
register DS 
X’hhhh’ Contents of 
register DI 
X’hhhh’ Contents of 
memory 
at ES:BX 


USER DATA 


As with ALERTS, APPC/PC logs USER DATA locally. Unlike 
ALERTS, however, APPC/PC does not send USER DATA 
information on the SSCP-PU session. The USER DATA Network 
Management vector contains the USER DATA Major Vector, the 
Correlator Subvector, and a variable number of USER DATA 
subvectors. 


The fields and values for the subvectors are unique to the type of 
error APPC/PC reports. It is beyond the scope of this document 
to describe the contents of the adapter log and status block that 
APPC/PC returns in the USER DATA subvectors. For this 
information, consult the IBM Token-Ring Network PC Adapter 
Technical Reference Manual. 
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The user data subvectors fall into two categories: 


e DLC link status 
e Counter overflow. 


The descriptions of these USER DATA subvectors are as follows: 


DLC Link Status 


Description: The IBM Token-Ring Network data link control 
software detected a link status that indicates an 
error condition. 

For DLC link status errors, the USER DATA subvectors are: 

e Adapter (0/1) X’hh’ 

e User DataCode X’10’ condition = Link Status 

e Qualifier Data 

— X’hhhh’ DLC Status Block 
— 6X’hh’ Remote adapter node address 


— X’00hh’ Remote Service Access Point 
— 6hh’ Frame Reject (FRMR) data (when applicable) 


Counter Overflow 


Description: The IBM Token-Ring Network data link control 
software detected a statistical counter overflow. 


For Counter Overflow errors, the USER DATA subvectors are: 
e Adapter (0 | 1) X’hh’ 
e User Data Code X’0020’ condition = 
Log Counter 
Overflow 
e User Data Log ID 
— For Adapter Counter Overflow 


Log ID X’0001’ 
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Qualifier Data 14X’hh’ Adapter Log 
(14 bytes) 


— For DLC Link Counter Overflow 
Log ID X’0002’ 
Qualifier Data 6X’hh’ Remote adapter 
node address 
X’hhhh’ Remote Service 
Access Point 
16X’hh’ DLC Link Log 
— For DLC SAP Counter Overflow 
Log ID X’0003’ 


Qualifier Data 18X’hh’ DLC SAP Log 
(18 bytes) 


SDLC Problems 


APPC/PC reports failures in an SDLC link through a SYSLOG of 
type X’0016’ to indicate the failure of the adapter or a network 
resource. If a link failure occurs APPC/PC attempts to reactivate 
SDLC five times. If this is not successful you must fix the line 
problem and re-issue the ACTIVATE DLC verb. The following 
timers within SDLC indicate when INOP conditions can occur. 
The abbreviations used below are: 

CTS: Clear To Send 

DCE: Date Communication Equipment (a modem) 

RTS: Request To Send 

DTE: Data Terminal Equipment 

DSR: Data Set Ready 


DISC: Disconnect command 


UA: Unnumbered Acknowledgement 
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30-millisecond CTS Dropout 


If the CTS signal from the modem goes inactive during an active 
transmission (that is, when RTS from the DTE is active), SDLC 
initiates a 30-millisecond time-out. SDLC generates a link failure 
if DSR remains inactive after 30 milliseconds. 


30-millisecond DSR Dropout 


If there is an abnormal transition in DSR status from the modem 
(that is, the modem changes from active state to inactive state 
without the DTR changing from active to inactive state), SDLC 
will wait for 30 milliseconds for DSR to become active again. 
SDLC generates a link failure if DSR remains inactive after 30 
milliseconds. 


40-second Transmit Failure 


If a transmit operation continues for more than 40 seconds, SDLC 
generates a link failure. This time limit applies for both primary 
and secondary link stations. This time interval is sufficient to 
transmit 4 kilobytes of data using the maximum supported frame 
size and the minimum supported speed of 1200 bits per second. 


5-second DISC Not Received 
Time-out 


After a secondary station receives a “close,” it waits for 5 seconds 
for a DISC from the primary station. If the DISC arrives within 
this time limit, the secondary station responds with a UA and 
waits for the primary station to terminate the link in a normal 
fashion. If the DISC does not arrive within the 5 seconds, the 
secondary station terminates the link connection and stops 
responding to the primary station. 


10-second Inactivity Time-out 


A secondary SDLC station generates a link failure if it detects 
line inactivity (no polls from the primary station) for more than 
10 seconds. 
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Appendix E. Sample Programs 


The APPC/PC Structures and Sample Programs diskette included 
with the APPC/PC Installation and Configuration Guide contains 
a set of sample programs written in IBM PC Macro Assembler 
language and assembled using the IBM Macro Assembler Version 
2.00. These programs represent two small application subsystems 
and the two sides of a cooperating transaction program. The 
sample programs run on two IBM PCs connected by the IBM 
Token-Ring Network. The diskette includes the following four 
executable programs: 


SEND_AS A sample sending side application subsystem. 
SEND_TP A sample sending side transaction program. 
RCV_AS A sample receiving side application subsystem. 
RCV_TP A sample receiving side transaction program. 


The APPC/PC Structures and Sample Programs diskette also 
includes files containing the listings for each program: 
SEND_AS, SEND_TP, RCV_AS, and RCV_TP. These programs 
illustrate the design of an application subsystem and the coding 
of APPC/PC verbs using the macro-assembler verb- request 
parameter lists included on the diskette. 


The application subsystem programs (SEND_AS.EXE and 
RCV_AS.EXE) are minimum application subsystems as described 
in Chapter 5, “Using Control Verbs.” Both of these application 
subsystems follow the same basic operation sequence: 


e Verify that APPC/PC is loaded. 

e Translate (CONVERT) ASCII names to EBCDIC. 

e Define the Passthrough exit to APPC/PC. APPC/PC uses this 
exit to communicate the TP_ID between the application 
subsystem and its transaction program. This exit also 
communicates the CONV_ID to remotely allocated 
transaction programs. 


e Initialize the session using the following APPC/PC verbs: 
ATTACH _PU defines the Physical Unit. 
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ATTACH _LU defines the Logical Unit. 

ACTIVATE DLC opens the DLC adapter. 

CNOS AUTO_ACTIVATEs the single session between the 
two nodes. 


e Execute the transaction program. 


On the receiving side, the application subsystem performs a 
GET_ALLOCATE loop while it waits for an incoming 
ALLOCATE. When the application subsystem receives an 
ALLOCATE, it verifies the ALLOCATE and then initiates the 
receive side transaction program. 


e After the sample transaction program terminates, the 
application subsystem takes down the session with the 
following APPC/PC verbs: 


CNOS sets the session limit to 0. 
DETACH LU deactivates the Logical Unit. 
DETACH_PU deactivates the Physical Unit. 


e The application subsystem then resets the Passthrough exit 
address, and 


e Exits to DOS. 


The sample transaction programs (SEND_TP.EXE, and 
RCV_TP.EXE) are small programs that demonstrate the use of 
conversation verbs. Both of these programs follow the same 
operation sequence: 


e Inform (TP_INITIATE) APPC/PC and the application 
subsystem that the transaction program has begun, and in 
turn, receive the TP_ID (and in the case of the receive side, 
the CONV_ID) from the application subsystem (see 
Chapter 2, “Developing an Application Subsystem”). 


e Set up the conversation (ALLOCATE). 


e Execute some conversation verbs (SEND _DATA and 
RECEIVE _AND_WAIT). 


e Take down the conversation (DEALLOCATE). 


e Inform APPC/PC that the transaction program is complete 
(TP_ENDED). 
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e Exit to the application subsystem. 


Each transaction program requires a TP_ID and a CONV_ID in 
order to issue valid conversation verbs. On the send side, the 
TP_ID is returned on the TP_STARTED verb issued by the 
application subsystem, and the CONV_ID is returned on the 
ALLOCATE verb. The receive side, on the other hand, need only 
have these values communicated to it by the application 
subsystem when the receive side is initiated, since the 
ALLOCATE has already been issued by the send side. 


To provide the same interface to both transaction programs, the 
application subsystem defines a user-defined verb for the sample 
application subsystem. 


Sample User-Defined Verb 


The transaction program uses this user-defined verb to request 
the TP_ID (and in the case of the remotely initiated transaction 
program, the CONV_ID) from the application subsystem. 


Supplied Parameters: 
TP. INITIATE LOCAL REMOTE INDICATOR (variable) 


TP_NAME (variable) 


LU_NAME (variable) 
Returned Parameters: 


TP_ID (variable) 
CONV_ID (variable) 


RETURN_CODE (variable) 


Supplied Parameters: 


LOCAL REMOTE_INDICATOR specifies whether this 
transaction program is local (that is, the program that will issue 
the ALLOCATE), or remote (that is, the program allocated by a 
remote transaction program). 


TP_NAME specifies the name of the transaction program the 
application subsystem is initiating. 


LU_NAME specifies the name of the partner LU at which the 
transaction program is being initiated. 


Returned Parameters: 
TP_ID specifies the TP_ID. 


CONV_ID specifies the CONV_ID, when a remote transaction 
program is executing the TP_INITIATE. 


RETURN_CODE specifies the return code indicating whether 


the TP_INITIATE verb is acceptable (0) or not acceptable 
(non-0). 


Sample Conversation 


The sample conversation performed by the transaction program is 
as follows. The send side of the conversation executes the 
following verbs: 


TP_INITIATE(LOCAL) causes the application subsystem to 
issue a TP_ STARTED verb and return the TP_ID. 


ALLOCATE causes APPC/PC to allocate a conversation and 
return the CONV_ JID. 


SEND_DATA sends data on the conversation. 
DEALLOCATE deallocates the conversation. 


TP_ENDED informs APPC/PC that the transaction program 
is complete. 


The receive side of the conversation executes the following verbs: 


TP _INITIATE(REMOTE) returns the TP_ID and the 
CONV _ID to the transaction program. 


RECEIVE _AND_ WAIT receives the transmitted data. 
RECEIVE _AND_ WAIT receives the deallocate. 
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TP_ENDED informs APPC/PC that the transaction program 
is complete. 


Sample Program Execution 


The procedure for running the sample program is: 


1. 


Configure the hardware of two IBM PCs which are to run the 
sample program (they should each contain an IBM 
Token-Ring Network adapter). 


Use the APPC/PC Configuration program to prepare two 
APPC/PC diskettes (one for each side). 


The send side diskette must contain: 


e An APPC/PC configuration file. Use the configuration 
program to create a configuration file as described in the 
APPC/PC Installation and Configuration Guide. Use the 
default values with the following changes: 


— On the “IBM Token-Ring DLC Parameters” screen, 
set the “Load Option” parameter to 1. 


— On the same screen, set the “Local Node Address” 
parameter to a soft address of 400000000001. 


e APPC/PC system files (APPC/PC commands and 
execution code) 


e The sample programs, SEND_AS.EXE (the sample 
application subsystem) and SEND_TP.EXE (the sample 
transaction program). 


The receive side diskette must contain: 


e An APPC/PC configuration file. Use the configuration 
program as described in the APPC/PC Installation and 
Configuration Guide to create a configuration file. Use 
the default values with the following changes: 


— On the “IBM Token-Ring DLC Parameters” screen, 
set the “Load Option” parameter to 1. 
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— On the same screen, set the “Local Node Address” 
parameter to a soft address of 400000000002. 


e APPC/PC system files (APPC/PC commands and 
execution code). 


e The sample programs, RCV_AS.EXE (the sample 
application subsystem) and RCV_TP.EXE (the sample 
transaction program). 


3. Boot the two IBM PCs. 


4. Type TOKREUI and press Enter to load the support interface 
code for the IBM Token-Ring Network adapter. 


5. Load APPC/PC on each machine. 
6. On side two, type RCV_AS and press Enter. 


The application subsystem prints a few messages to let you 
know that it has brought up the node and that it is waiting 
for an incoming ALLOCATE. 


7. On side one, type SEND_AS and press Enter. 


This action starts the sending application subsystem, which 
activates the node, and executes the transaction program. 


When the transaction program begins execution, the receive side 
of the transaction program (RCV_TP.EXE) is automatically 
loaded and executed when the incoming ALLOCATE is received 
from the send side. After receipt of the ALLOCATE, the send 
side sends a message, and the receive side displays the received 
message. Each side terminates the transaction and brings down 
the session. 


The sample program can be rerun by simply executing the 
application subsystem. 
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Modifying the Sample Program 
for SDLC 


The sample program provided on the diskette is written to use the 
IBM Token-Ring Network. To run this sample program on an 
SDLC connection, modify the program as follows: 


e Use the configuration program to define an SDLC Data Link 
Control (DLC). 


e Change the application subsystem programs (SEND_AS.ASM, 
and RCV_AS.ASM) to refer to the correct DLC. 


The places in these programs that include DLC-specific 
information are as follows: 


In the ATTACH LU control block (the PARTNER _LU 
structure), the following fields identify the DLC. 


dlename Identifies the DLC Adapter Name (for 
example, ‘SDLC’ or ‘ITRN’). The value 
should match that entered on the 
configuration menu. 


adaptid Indicates the adapter number (for example, 
0 or 1). This field should have a value of 0 
for SDLC operation. 


adp_adrlen Indicates the length of the Partner LU 
adapter address in bytes. This field should 
have a value of 0 because the SDLC code 
does not use this field. 


The following fields in the ACTIVATE DLC control 
block identify the DLC. 


dlename Identifies the DLC Adapter Name (‘SDLC’ 
or ‘ITRN’). The value should match that 
entered on the APPC/PC configuration 
menus, and that found in the Partner LU 
portion of the ATTACH LU control block. 


adaptid Indicates the adapter number (for example, 
0 or 1). This field should have a value of 0. 
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Note: If the program is to use a switched line, you should 
prompt the user to establish the switched connection (that is, dial 
the originating telephone). The application subsystem should 
display this prompt after issuing the ACTIVATE DLC verbs and 
then it should wait for acknowledgment from the user in the form 
of a keystroke before continuing. 


After entering these changes to both of the application subsystem 
programs, SEND_AS.ASM and RCV_AS.ASM, assemble each 
using the IBM Macro Assembler (Version 2.0). Then link each 
program using the latest version of the link program to create 
new EXE files. Execute the programs using the same 
instructions as for operation with an IBM Token-Ring Network. 


APPC/PC—CICS Sample Program 


The following program is an assembler-language program written 
as a transaction program to CICS. This program was written 
using the EXEC CICS GDS format and can be run against the 
receive side transaction program supplied for the sample for two 
IBM PCs. 


Appendix F, “Sample CICS Host Configuration for APPC/PC” 
contains the CICS and VTAM definitions needed to run this 
program. 


*ASM XOPTS(CICS,GDS,SOURCE) 
KEKRKKKREEKEEKKEKKRKEEREKEKEERKEEEEKEKKRERREEKEKRKEKEKEKKEKEKEKEEKEKKEREKEKEKEKEKEE 
* * 
SAMPLE TRANSACTION PROGRAM SEND SIDE * 
* 
FUNCTION: This transaction program runs on the CICS . 
subsystem. It issues the verbs necessary to transmit* 
a simple string of data to a transaction program on * 
the receive side. 


* 
* 
* 
ALLOCATE * 
CONNECT PROCESS * 
SEND * 
SEND LAST WAIT * 

* 

* 


FREE 


* 
* 
* 
* 
* 
* 
* 
* METHOD: Issue the following verbs 
* 
* 
* 
«x 
* 
KEK KEK KE KK KEKE KEK KEKE KEKE RREKKEREKREEKEEERERKEKEKEKKEKEEKKEKKEKER 
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DFHEISTG DSECT 


SMP1 


INTRO 


USING *,2,3 

SPACE 2 

DFHEIENT CODEREG=(2,3) 

PRINT NOGEN 

B INTRO 

SPACE 2 

DC CL4'SMP1' IDENTIFY PROGRAM 
SPACE 2 

DS OH 


REAR REKEREKKEKEKEEKEEKEEKEKEKKEEEKEEKEEKKKEEKEKKEKEEEKEEEE 


* 


ALLOCATE * 


REECE KK KKK KKK EKREKEKKEKKEKEKKKEKKKKKKKKKEKKKKKKKKEKKK 


EXEC CICS GDS ALLOCATE 
SYSID('APPC' ) 
CONVID(CONVID) 
RETCODE (RCODE ) 
MODENAME ( 'normal' ) 

CLI RCODE,X'O1' 


BE QUIT 
CLI RCODE,X'02' 
BE QUIT 

SPACE 2 


HREKEKEKEKEEKEEKEEREKKEEKKEKEKKEEKEEKEKEKEKEREKKEEKKKKKKKKKKKKKKKKEKE 


* 


CONNECT PROCESS i 


WHKKKKKEKKKEKEKKEEKEEKEKEEKERKKEEKEKKEKEEKEKEKKERKKEKKKKKRKEKK 


EXEC CICS GDS CONNECT PROCESS 
PROCNAME('rcvtp' ) 


PROCLENGTH (5) 
SYNCLEVEL (0) 
CONVID(CONVID) 
CONVDATA (CONVDATA) 
RETCODE (RCODE) 

CLI RCODE,X'03' 

BE QuIT 

CLI RCODE,X'04' 

BE QUIT 

CLI RCODE,X'05' 

BE QUIT 

SPACE 2 


HHKKEHKKEKK KK EKER EEE KEKE KEKE KEKEK KEKE KEKKEKKKEKKKKKEKKKEKK 


* 


SEND * 


HEKEKRERERKK IKKE REE KEKE EER EERE EKER REREKIKREKEKEKKEKEEKKKKKKAK 


EXEC CICS GDS SEND 


FROM (REQ1) 
FLENGTH (45) 
CONVID(CONVID) 
CONVDATA (CONVDATA) 
RETCODE ( RCODE) 

CLI RCODE,X'03' 

BE QUIT 

CLI RCODE,X'04' 

BE QUIT 

CLI RCODE,X'0S' 

BE QUIT 

SPACE 2 


ee eH 


+ ee ee OF 


* ee Oe OF 
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KAREKRKRKEKEKREKEEKEKKEEREKEEEKEEKEKREKKEKEEKKEKKEKEKKKEEEKEKKEKEKKEEE 


* 


SEND LAST WAIT * 


KEK KKKKRKEEEEKEKEEEKEKEEKKEEKKEKEKKEREKEEKKKKKEKKKEREKEEKKKEKEK 


EXEC 


SPACE 


CICS GDS SEND LAST WAIT 
CONVID(CONVID) 
CONVDATA (CONVDATA) 
RETCODE ( RCODE) 
RCODE,X'03' 

QUIT 

RCODE,X'04' 

QUIT 

RCODE,X'05' 

QUIT 

2 


RARKEKKKKRERKEEKKREKEEEKREREEEKEEEEEEEKEKRREREKKKEKEEKKKKKKEKRKEKEKE 


* 


FREE tas 


MERE KEEKEEKKEKEKEEKKKKKKKKKEEKEKKEEKEKREKKKKREKKKEREK 


QUIT 


CONVID 
RCODE 
CONVDATA 
APSYSID 
INLEN 


REQ1 
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EXEC 


EJECT 


CICS GDS FREE 
CONVID(CONVID) 
CONVDATA ( CONVDATA) 
RETCODE (RCODE ) 
RCODE,X'03! 

QUIT 

RCODE,X'04' 

2 

OH 

CICS RETURN 


F'O!' CONVERSATION IDENTIFIER 
XL4'00' RETURN CODE INFORMATION 
XL24'00' CONVERSATION RELATED DATA 
CL4 SYSTEM ID 

F 


DC XL2'002D' 

DC XL16'2A2A2A2044617461207472616E736D69' 
DC XL16'747465642066726F6D20434943532074' 
DC XL11'6F205243565450202A2A2A' 


* 


* 


Appendix F. Sample CICS Host 
Configuration for APPC/PC 


This appendix contains the CICS and VTAM definitions 
necessary to use APPC/PC with a connection between an IBM PC 
and a host system. 


DEFINITIONS FOR APPC/PC - CICS SAMPLE TEST 


RRKKKKEEKEKKEEKKKKKKKKKKKKKKKEKKEK 


kkeke* CICS DEFINITIONS ***** 
RRR IT TR IR RIOR RK aR RK 


eekxk* PCT DEFINITION ***** 


DFHPCT TYPE=ENTRY, 
TRANSID=SMP1, 
PROGRAM=SMP1, 
TWASIZE=160, 
DTB=(YES), 
SPURGE=YES, 
TPURGE=YES, 
INBFMH=ALL, 
RSL=PUBLIC, 
RSLC=NO 


+ + + & FF FF HK 


*x*k* PPT DEFINITION ***** 


DFHPPT TYPE=ENTRY , PROGRAM=SMP1,PGMLANG=ASSEMBLER , RSL=PUBLIC 


weeee = 6TCT DEFINITION ***** 


APPC DFHTCT TYPE=SYSTEM, LUTYPE62 IBM PC 
TRMTYPE=LUTYPE62, 
ACCMETH=VTAM, 
CONNECT=AUTO, 
NETNAME=rcvlu (See note 1) 
SYSIDNT=APPC, 
FEATURE=SINGLE, 
BUFFER=1024, 

RUSIZE=256, 
TCTUAL=255, 
TRMPRTY=O, 
TRMSTAT=TRANSCEIVE 


OS PR PS OS DS OS OS DG OO OS OG 
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KHKKEKEEREKKEEKEKEKRKEKEKEKRKKEKEKEKE 


xe*xek = VTAM DEFINITIONS ***** 
HR EER REEKREERREK EEK RK EKER 


****% NCP DEFINITION (FOR GROUP,LINE,PU,LU) ***** 

HDXGRP GROUP LNCTL=SDLC, SDLC CONNECTION 
DIAL=NO, LEASED LINK (NON-SWITCHED) 
TYPE=NCP, LINK DEDICATED TO NCP; I.E., NO PEP 
REPLYTO=3, LINK IDLE FOR 3 MINUTES, TIMEOUT 
NRZI=YES MODEM AND IBM PC MUST ALSO BE NRZI=YES 

SPACE 2 

HDXLN1 LINE ADDRESS=020, LINK ADDRESS FOR IBM PC ATTACHMENT 
CLOCKNG=EXT, EXTERNAL MODEM PROVIDES CLOCKING 
SPEED=9600, LINK SPEED ; 
DUPLEX=FULL, DUPLEX TRANSMISSION FACILITY 


ISTATUS=ACTIVE, LINK, PU AND LUS INITIALLY ACTIVATED 
SSCPFM=USSSCS, USE CHAR CODED MSGS ON SSCP-LU SESSION 
MODETAB=LU62MODT, USER DEFINED VTAM LOGON MODE TABLE 
DLOGMOD=SAMPLE DEFAULT ENTRY IN LOGON MODE TABLE 


SPACE 2 
SERVICE ORDER=(HDX260A) 
SPACE 2 
puname PU ADDR=1C, SDLC STATION ADDRESS FOR IBM PC 
ANS=STOP, STOP POLLING IF HOST SESSION FAILS 
MAXOUT=7, ALLOW MAX OF 7 OUTSTANDING SDLC FRAMES 
MAXDATA=265, MAX DATA TRANSFER TO IBM PC 
PACING=7, PACING WINDOW SIZE NCP TO IBM PC 
PASSLIM=8, SERVICE ORDER TABLE PASS LIMIT 
PUTYPE=2, IBM PC IS PU2.0 NODE TO NCP BOUNDARY 
RETRIES=(,1,4) PAUSE 1 SECOND BETWEEN 4 RETRIES 
SPACE 2 
revlu LU LOCADDR=1,ISTATUS=INACTIVE (See note 2) 
APPCPCO2 LU LOCADDR=2 , ISTATUS=INACTIVE 
APPCPCO3 LU LOCADDR=3 , ISTATUS=INACTIVE 
APPCPCO4 LU LOCADDR=4 , ISTATUS=INACTIVE 
APPCPCO5 LU LOCADDR=5 , ISTATUS=INACTIVE 
APPCPCO6 LU LOCADDR=6 , ISTATUS=INACTIVE 
APPCPCO7 LU LOCADDR=7 , ISTATUS=INACTIVE 


*#*k*k* MODETAB DEFINITION ***** 


LU62MODT MODETAB 
MODEENT LOGMODE=NORMAL 
MODEEND 
END 


*x***k APL DEFINITION FOR CICS ***** 
SENDLU APPL ABCNAME=SENDLU ,AUTH=(ALQ,PASS,VPACE) , 


DLOGMOD=NORMAL , MODETAB=LU62MODT, 
EAS=10,PARSESS=YES , VPACING=3 , SORSCIP=YES 


F.2 


re OS OK OS 


OS PS DS OS OS OS OS 


MK SO KO OO 


Notes: 


1. 


The NETNAME parameter specifies the network name to 
identify the APPC system to ACF/VTAM. In APPC/PC this 
name is specified on the ATTACH _LU verb with the 
LU_NAME parameter. 


The LOCADDR parameter specifies the LU local address of 
the session and is equivalent to a logical unit number. In 
APPC/PC this LU local address is specified on the 
ATTACH_LU verb with the LU_LOCAL_ADDRESS 
parameter. 
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Appendix G. APPC/PC 
Implementation of the LU6.2 
Architecture 


This appendix first describes the APPC architected optional 
functions supported by APPC/PC. It then describes the mapping 
of the APPC/PC verbs to the verbs as described in the SNA 
Transaction Programmer's Reference Manual for LU Type 6.2. 


Base and Option Sets for 
APPC/PC 


The APPC/PC program product supports the base set of APPC 
functions plus a list of optional subsetted functions. For a 
description of APPC function subsetting, see the topic 
“Product-Support-Subsetting” in Chapter 3 of SNA Transaction 
Programmer's Reference Manual for LU Type 6.2. Appendix A of 
the same manual describes each APPC subset in detail. 
APPC/PC supports the following optional subsets: 

e Immediate allocation of a session 

e Session-leve]l LU-LU verification 

e User ID verification 

e Program-supplied user ID and password 

e PIP data (sending only) 

e Logging of data in a system log 


e Flush the LU’s send buffer 
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e Prepare to receive 

e Long locks 

e Post on receipt with wait 

e Post on receipt with test for posting 

e Receive immediate 

e Test for request-to-send received 

e Get attributes 

e Get conversation type 

e Mapped conversation LU services component 
e MIN _CONWINNERS_TARGET parameter 
e RESPONSIBLE(TARGET) parameter 

e DRAIN TARGET(NO) parameter 

e LU-parameter verbs 

e LU-LU session limit 

e Maximum RU size bounds 


e Contention winner automatic activation limit 


Basic Conversation Verbs 


This section contains the cross-reference lists for basic 
conversation verbs and parameters. 


Cross-Reference for Basic Conversation 
Verbs 


The following table provides a cross-reference for Basic 
Conversation verbs: 


LU Type 6.2 Architecture APPC/PC Implementation 
ALLOCATE ALLOCATE 


fmackOUN = 
DEALLOCATE 

fsyncpr OSS OSOSOSOSOSOCOC*‘S 
WAIT 


Cross-Reference for Basic Conversation 
Verb Parameters 


The following tables provide a cross-reference for Basic 
Conversation verb parameters. 


P~* PD 


ALLOCATE parameters ALLOCATE parameters 
LU_NAME 
MBs ee I 


RETURN_CODE RETURN_CODE 


‘Note: 


TP_ID specifies the identifier for the instance of the transaction 
program issuing this verb. The application subsystem receives 
this value from APPC/PC when it starts the program. For more 
information on the TP_ID parameter, see the descriptions of the 
“CREATE TP” or “TP STARTED” verbs in Chapter 5, “Using 
Control Verbs.” 


APPC/PC does not support MODE_ NAME(SNASVCMG) from 
the API. 


APPC/PC does not support the APPC 
RETURN_CONTROL(DELAYED ALLOCATION_PERMITTED) 
option. It does, however, support an additional option: 
RETURN_CONTROL(WHEN_SESSION_FREE). 


The only synchronization level values that APPC/PC supports are 
NONE and CONFIRM. 


APPC/PC provides three security options: NONE, SAME, and 
PGM. 


APPC/PC 
CONFIRM parameters 


RETURN_CODE RETURN_CODE 
REQUEST_TO_SEND_RECEIVED REQUEST_TO_SEND_RECEIVED 


CONFIRMED parameters CONFIRMED parameters 
Pe a ae a Pe 
P S*RTORN CODE CC*d 


LU Type 6.2 APPC/PC 
DEALLOCATE parameters DEALLOCATE parameters 


RESOURCE : CONV_ID 
TYPE TYPE 
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LU Type 6.2 APPC/PC 

DEALLOCATE parameters DEALLOCATE parameters 
LOG_DATA LOG_DATA 
RETURN_CODE RETURN_CODE 


Note: 


APPC/PC does not support deallocation TYPE(LOCAL). 


FLUSH parameters FLUSH parameters 
(aa ee || | 
a 


LU Type 6.2 APPC/PC 
GET_ATTRIBUTES parameters GET_ATTRIBUTES parameters 


Pes Shek se at ee ee 
RESOURCE CONV_ID 


po RETURN_CODE 
Fo Sa ee ee UD 


OWN_FULLY_QUALIFIED OWN_NET_ID_ NAME 
LU_NAME OWN_LU_NAME 


PARTNER_LU_NAME PARTNER_LU_NAME 


PARTNER_FULLY_QUALIFIED_ PARTNER_FULLY_QUALIFIED _ 
LU_NAME LU_NAME 

MODE_NAME MODE_NAME 

SYNC_LEVEL SYNC_LEVEL 


SECURITY_USER_ID USER_ID 


Note: 


LU _ID specifies the identifier for the local LU under which the 
transaction program is executing. APPC/PC returns this value 
when the application subsystem identifies and initializes the LU 
by issuing the ATTACH _LU verb. For more information, see the 
description of the ATTACH LU verb in Chapter 5, “Using 
Control Verbs.” 


USER _ID specifies the user identification field from the 
ALLOCATE or incoming ALLOCATE if conversation level 
security was specified. 


LU Type 6.2 APPC/PC 
GET_TYPE parameters GET_TYPE parameters 


fe ee ee 
CONV_ID 
PY RETURN CODE 
TYPE 


LU Type 6.2 APPC/PC 
POST_ON_RECEIPT parameters POST_ON_RECEIPT parameters 


RENE 
CONV_1D 

FILL 
MAX_LENGTH 
PS *YP RETURN CODE 


LU Type 6.2 APPC/PC 
PREPARE _TO_RECEIVE PREPARE_TO_RECEIVE 
parameters parameters 


eee 1 
RESOURCE CONV_ID 


TYPE TYPE 
LOCKS LOCKS 
RETURN_CODE RETURN_CODE 


LU Type 6.2 APPC/PC 
RECEIVE_IMMEDIATE RECEIVE_IMMEDIATE 
parameters parameters 


PSP 
CONV_ID 

PILL 
MAX_LENGTH 
RETURN_CODE 
PCT A LENGTH 


DATA DATA_PTR 
DATA 


WHAT_RECEIVED WHAT_RECEIVED 
REQUEST_TO_SEND_RECEIVED REQUEST_TO_SEND_RECEIVED 
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LU Type 6.2 APPC/PC 
RECEIVE_AND_ WAIT RECEIVE_AND_WAIT 
parameters parameters 


DATA 
REQUEST _TO_SEND_ RECEIVED 


In the SNA Transaction Programmer’s Reference Manual for LU 
Type 6.2, the LENGTH parameter supplies the length of the 
buffer when the program issues the request. This parameter 
contains the actual number of bytes received when control is 
returned. APPC/PC uses the MAX LENGTH parameter to 
indicate the size of the buffer and the DATA LENGTH 
parameter to indicate the actual number of bytes received. 


DATA_PTR specifies the address of the buffer which is to 
contain the received data. 
APPC/PC 


LU Type 6.2 
REQUEST_TO_SEND parameters REQUEST_TO_SEND parameters 


PPD 
RESOURCE CONV_ID 
PL ROR CODE 


SEND_DATA parameters SEND_DATA parameters 
fee ee ey 
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LU Type 6.2 APPC/PC 
SEND_ERROR parameters SEND_ERROR parameters 


RESOURCE — 


REQUEST_TO_SEND_RECEIVED REQUEST_TO_SEND_RECEIVED 


TEST parameters TEST parameters 
ai a |e nee, 
RETURN_CODE 


WAIT parameters WAIT parameters 
eae green [2 | ee ee 


Mapped Conversation Verbs 


This section contains the cross-reference lists for mapped 
conversation verbs and parameters. 


Cross-Reference for Mapped Conversation 
Verbs 


The following table provides a cross-reference for Mapped 
Conversation verbs: 


G-8 


BACROU te eee 
[MC_POST_ON_RECEIPT [SSS 


Mer 
RWAE =e ee 


Cross-Reference for Mapped Conversation 
Verb Parameters 


MC_RECEIVE_AND_WAIT MC_RECEIVE_AND_WAIT 


The following tables provide a cross-reference for Mapped 
Conversation verb parameters. 


LU Type 6.2 APPC/PC 
MC_ALLOCATE parameters MC_ALLOCATE parameters 
LU_NAME PARTNER_LU_NAME 


ee ee 
a 6 
RETURN_CODE 


Note: 


APPC/PC does not support the APPC 
RETURN_CONTROL(DELAYED_ALLOCATION_PERMITTED) 
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option. It does, however, support an additional option: 
RETURN_CONTROL(WHEN_SESSION_ FREE). 


The only synchronization level values that APPC/PC supports are 
NONE and CONFIRM. 


APPC/PC provides three security options: NONE, SAME, and 
PGM. 


MC_CONFIRM parameters MC_CONFIRM parameters 
ee 1 ee ane 


LU Type 6.2 APPC/PC 
MC_CONFIRMED parameters MC_CONFIRMED parameters 


aera TERY 577 
RESOURCE CONV_ID 
PRR CODE 


LU Type 6.2 APPC/PC 
MC_DEALLOCATE parameters MC_DEALLOCATE parameters 


eee eee 
TYPE 


Note: 
APPC/PC does not support deallocation TYPE(LOCAL). 
LU Type 6.2 APPC/PC 
MC_FLUSH parameters MC_FLUSH parameters 
ee ar INS 6S eee 


RESOURCE CONV_ID 
Eo 
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RESOURCE 
LOUW_IDENTIFIER pe 


LU Type 6.2 APPC/PC 
MC_GET_ATTRIBUTES parameters | MC_GET_ATTRIBUTES parameters 


OWN_FULLY_QUALIFIED _ OWN_NET_ID_ NAME 
LU_NAME OWN_LU_NAME 
PARTNER_LU_NAME PARTNER_LU_NAME 
PARTNER_FULLY_QUALIFIED _ PARTNER_FULLY_QUALIFIED_ 
LU_NAME LU_NAME 

MODE_NAME MODE_NAME 

SYNC_LEVEL SYNC_LEVEL 
SECURITY_USER_ID USER_ID 


Note: 


LU_ID specifies the identifier for the local LU under which the 
transaction program is executing. APPC/PC returns this value 
when the application subsystem identifies and initializes the LU 
by issuing the ATTACH_LU verb. For more information, see the 
description of the ATTACH LU verb in Chapter 5, “Using 
Control Verbs.” 


USER_ID specifies the user identification field from the 
ALLOCATE or incoming ALLOCATE, if conversation level 


security was used. 


LU Type 6.2 APPC/PC 
MC_PREPARE_TO_RECEIVE MC_PREPARE_TO_RECEIVE 
parameters parameters 


TP_ID 


RESOURCE CONV_ID 
TYPE 
LOCKS LOCKS 


RETURN_CODE RETURN_CODE 


Note: 


TYPE(SYNC_LEVEL) is equivalent to TYPE(CONFIRM) if 
ALLOCATE SYNC_LEVEL is CONFIRM. 
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LU Type 6.2 APPC/PC 
MC_RECEIVE_AND_WAIT MC_RECEIVE_AND_WAIT 
parameters parameters 


DATA 
REQUEST_TO_SEND_RECEIVED 
MAPNAME DCC 


Note: 


In the SNA Transaction Programmer’s Reference Manual for LU 
Type 6.2 for MC_ RECEIVE AND WAIT, the LENGTH 
parameter supplies the length of the buffer when the program 
issues the request. This parameter contains the actual number of 
bytes received when control is returned. APPC/PC uses the 

MAX LENGTH parameter to indicate the size of the buffer and 
the DATA_ LENGTH parameter to indicate the actual number of 
bytes received. 


LU Type 6.2 APPC/PC 

MC_RECEIVE_IMMEDIATE MC_RECEIVE_IMMEDIATE 

parameters parameters 
PSS TPID 

RESOURCE CONV_ID 

LENGTH MAX_LENGTH 

RETURN_CODE RETURN_CODE 


PSY ATALLENGTH 
DATA 
pWaAP_NaME SCs 
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LU Type 6.2 APPC/PC 
MC_REQUEST_TO_SEND MC_REQUEST_TO_SEND 
parameters parameters 


TP_ID 
CONV_ID 
RETURN_CODE 


APPC/PC 
MC_SEND_DATA parameters 


MC_SEND_ERROR parameters 


MC_TEST parameters 
RBTURN_CODE 


Note: 


APPC/PC does not support MC_TEST(POSTED). 
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Control Verbs 


This section contains the cross-reference lists for control operator 
verbs and parameters. 


Cross-Reference for Control Verbs to 
APPC/PC Verbs 


LU Type 6.2 Architecture APPC/PC Implementation 
ACTIVATE_SESSION See aaa eee 
CHANGE_SESSION_LIMiIT Pee 


INITIALIZE_SESSION_LIMIT sos 
RESET _SESSION_LIMIT CNOS 

PROCESS_SESSION_LIMIT 

[DEACTIVATE SESSION | —SsSsSsS—S—S 


eer 

Pe epee Paes 

a nei 

ae pe eee 2 Scie tall OM ANGE US ete 
a se ACTIVATE OG, Aa) 
ee ee 7s es 
ee eee i eee 
ee 
ee eee 
ee eee eee 
ede eerie eee 
a ee 
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Cross-Reference for Control Verbs to 
APPC/PC Verb Parameters 


LU Type 6.2 APPC/PC 
INITIALIZE_SESSION_LIMIT, CNOS parameters 
RESET_SESSION_LIMIT and 
PROCESS_SESSION_LIMIT 

parameters 

(Note: The above verbs will be 

abbreviated below as ISL, RSL, 

and PSL respectively.) 


Pape eee tee tee oe ante eOULIO 

LU_NAME ISL,RSL,PSL_ | PARTNER_LU_NAME 
MODE_NAME ISL,RSL MODE_NAME_ SELECT 
Po SET_NEGOTIABLE 


LU_MODE_SESSION_LIMIT ISL PARTNER_LU_MODE_SESSION_ 
LIMIT 


TSSCS™~™S™SCCSCSCSAUTIOLATIVATE CS 
RETURN_CODE ISL,RSL,PSL 


Note: 


AUTO_ACTIVATE specifies the number of contention winner 
sessions that APPC/PC automatically activates before any 
transaction program ALLOCATE requests occur. 


SET_NEGOTIABLE specifies whether the 

PARTNER _LU_MODE_SESSION_LIMIT specified in the 
CNOS verb will also be used to override the current settings for 
MODE MAX NEGOTIABLE _SESSION_LIMIT, as given in the 
ATTACH _LU verb (or previously overridden by an earlier CNOS 
verb with this parameter set to YES). In this case, a normal 
CNOS negotiation still takes place. If the CNOS verb has no 
parameter errors in it, the new value takes effect as the local 
value for this and future negotiations. The partner LU (in the 
parallel session case) can still negotiate the suggested values 
downwards. 
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Network Management Verb 


LU Type 6.2 Architecture APPC/PC Implementation 
PS *YRANSFER_MS_DATA 


Other APPC/PC Services 


The following table list verbs not architecturally defined: 


LU Type 6.2 Architecture APPC/PC 
CONVERT 


po PASSTHROUGH 
po SET_PASSTHROUGH 


TRACE 
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Appendix H. ASCIT/EBCDIC 
Translation Tables 


This appendix describes the three kinds of ASCII/EBCDIC 
conversion tables you can specify for use by the CONVERT verb 
(for information on the CONVERT verb, see Chapter 9, “Other 
APPC/PC Services.” The type A and type AE tables are internal 
to APPC/PC. The type G table is user-supplied; its file name is 
specified on the APPC/PC configuration menus. The conversion 
table types correspond to the symbol string types A, AE, and G 
described in the SNA Transaction Programmer’s Reference 
Manual for LU Type 6.2. For information on the APPC/PC 
configuration menus, refer to the APPC/PC Installation and 
Configuration Guide. 


The type A table converts characters including uppercase A-Z; 
numerics 0-9; and special characters $, #, and @. This table also 
converts lowercase ASCII characters to uppercase EBCDIC 
characters. When you specify this table, APPC/PC requires the 
first character in each string to be an uppercase letter or one of 
the three special characters. The string can contain trailing 
blanks. 


The type AE table converts characters to the same characters as 
the type A table but also converts lowercase a-z and the period (.). 
APPC/PC does not place any restrictions on the first character of 
the string, and the string can contain trailing blanks. 


The type G table is a user-defined table that converts any 
character. This appendix includes a sample of a type G table that 
you can edit to satisfy the specific conversion requirements of 
your program. The APPC/PC diskette includes a file named 
APPCGTAB.DAT, containing this sample type G table. 


The format of a conversion table consists of 32 lines of 32 
characters each. Each line represents 16 “printable” hexadecimal 
characters followed by a carriage return and line feed. The first 
16 lines provide the information for ASCII to EBCDIC conversion 
and the second 16 lines provide the information for EBCDIC to 
ASCII conversion. The table must include all 32 lines. 


When APPC/PC performs a conversion, it uses the numeric 
equivalent of each incoming character as a 0-origin index into the 
conversion table. This index specifies the table location 
containing the hexadecimal value of the converted character. 

For example, assume that the 48th position in the table contains 
a value of X’F0’. APPC/PC will then convert incoming 
characters with a value of 48 (X’30’) to a value of 240 (X’F0’). 


e TABLE A 


OODDDDDDNDDNNNDNDNNDDNDNNNDNDNNNONNNNN 
OODDDDDNDNDNDDNONNNDDNDNNDNNNN0000000 
40000007B5BO00000000000000000000 
FOFLF2F3F4F5F6F7F8F9I000000000000 
7TCC1IC2C3C4C5CEC7TC8C9DID2D3D4D5D6 
D7D8D9E2E3E4E5EGE7E8E90000000000 
OOC1C2C3C4C5C6C7C8CIDID2D3D4D5D6 
D7D8D9E2E3E4E5E6E7E8E90000000000 
OODDDDDDDNDNDNDNDNDNDDONNNND0NN0NN000N 
OODDDDDDNDNNNNDNDNNND0N0NN000000000 
00000000000000000000000000000000 
OODDDD0DDNDONNDDNNDNDNNDNNNNDNNNN0N000N 
OODDDDNDDNNDONNNNNNDN00000000000000 
OODDDD0DNDNDDNNDNNDNNNNNNDN000N0000000 
OOD00000000000000000000000000000 
OOODDDNDNDNDDNDNNDDNNDNDDNND0DNDNN00000N 
OODDDDDNN0DNNDNNDNDDNDN000D0000000000 
00000000000000000000000000000000 
OODDDD00DN0DNDN0NNN00000000000000000 
OODDDDDDNDD0DNDNDNNDDNNDNN00DND000000N 
20000000000000000000000000000000 
00000000000000000000002400000000 
OODDDD00DDDNDNNDDNNDNND0N00000000000 
00000000000000000000002 340000000 
00616263646566676869000000000000 
OOGCAGBECEDEEGF707172000000000000 
0000737475767778797A000000000000 
OODDDDDDNNDNDNDDNNNDNNNNNNN0N000000 
00414243444546474849000000000000 
O04A4B4C4D4E4F'505152000000000000 
0000535455565758595A000000000000 
OODDDDDNDNNDNDNDNDNNDNDNNNN0NN00N00000000 
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TABLE AE 


OO0D00DD0DNNDNNNNDNDNNNDNNNNNNNNNNNNNN 
ooddd0NNDNNNNNNDNONNNNNN0000000000 
4000007B5BO000000000000000004B00 
FOFIF2F3F4F5F6F7F8F9000000000000 
7CC1C2C3C4C5C6C7C8CIDID2D3D4D5D6 
D7D8D9E2E3E4E5E6E7E8E90000000000 
00818283848586878889919293949596 
9798 99A2A3A4A5A6A7A8A90000000000 
‘olotezezololelelefelelelereretetelelereyejejelelelelererelerere) 
OO0000D0D0N0DN00N000NN000N00000000000 
OO00DD0DNDNNDNNNNN0DNNDDNNNNN0NN000000 
OODDDD0DO0NDNDNDNN0DN000N00000000000000 
O00000D000000000000000000000000000 
O0D0DDDDNNDNNDDNDNDNONNNNNN00N0N0000000N 
O00DDD0D0DNDNNDNNNNDNN0NNNNNNN00N0000000 
00000000000000000000000000000000 
O000DDDDNDDNDNNDNDNDNOONNNNNNNNNNNNNN0NN 
OOO0DDDDNNNDNDNNNDONNONN0N0N0N0N00NN0N00N 
OODDDDDONDNNNDN00N0D00000000000000 
‘el ote telelelereloreroteteloteleteleleleleletelelelereleleleleye) 
20000000000000000000002E00000000 
00000000000000000000002400000000 
00000000000000000000000000000000 
00000000000000000000002340000000 
00616263646566676869000000000000 
OO6AGBECEDGEGF707172000000000000 
0000737475767778797A000000000000 
CODDDDND0DNNDNNNDNNNNNN0NNND0000000000 
00414243444546474849000000000000 
O04A4B4C4D4E4F505152000000000000 
0000535455565758595A000000000000 
30313233343536373839000000000000 
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e TABLE G 


The following is a properly formatted sample of the type G 
table you can supply for APPC/PC: 


00010203372D2E2F1605250BOCODOEOF 
LOLTIZIZ3SC3D322618193F 27221D351F 
405A7F7B5B6C507D4D5D5C4E6B604B61 
FOFIF2F3F4F5F6F7F8F97A5E4C7E6E6F 
7TCC1IC2C3C4C5C6CTCB8CIDID2D3D4D5D6 
D7D8D9E2E3E4E5E6E7E8E9ADEOBD5F6D 
79818283848586878889919293949596 
9798 99A2A3A4A5A6A7A8A9CO6ADOA1ON7 
PPPPREE PES P REPRE PPEPEPPPEPPPr Pree 
PEPPY PFEPPPEPPPRPEPPEPPPPPEP EP Pre er 
PEP PEPPER EPPPPEPPPEPPEPEPYPEPEPEEEE 
PEFEPPPEPEPIoPEEOPPPEP PEPE RPE Pree 
FPEREFFFFEEFFFPFFFPFFFPFEFEEFEEFEFEFFFFE 
PUPRUEPEPPEPEIPE PPP PPP Pere Pere rr 
FEFFFPFFFFFFFFFFFEFFFFFFFFFFFFFFFFFE 
FREPEPPEPPEFEPSEPPPPPPrPrrerrrrrrerer 
00010203FFO9FF7FFFFFFFOBOCODOEOF 
10111213FFFFO8FF1819FFFFFFIDFFIF 
FFFFICFFFFOA171BFFFFFFFFFFO50607 
FFFFLOFFFFIEFFO4FFFFFFFFI415FF1A 
2OFFFFFFFFFFFFFFFFFFFF2E3C282BFF 
2O6FFFFFFFFFFFFFFFFFF21242A293B5E 
2DZUEFFFFFFFFRFEEFEFFE /C2C255F3E3F 
FFFFFFFFFFFFFFFFFF603A2340273D22 
FF616263646566676869FFFFFFFFFFFF 
FF OAGB6CODOEOF7O7172FFFFFFFFFFFF 
FFVJETS74A7TS7677 78797 AFPPRFEFSBFEFF 
FFFPFFEFPEFFPFFFFFFFPPFFEEPYSDFFFE 
7B414243444546474849FFFFFFFFFFFF 
7D4A4B4C4D4E4F505152FFFFFFFFFFFF 
5CFF535455565758595AFFFFFFFFFFFF 
30313233343536373839FFFFFFFFFFFF 
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Appendix I. Statement of Service 


IBM will provide service for valid program-related defects in the 
IBM APPC/PC program product at no additional charge. 
Program service is available until June 30, 1987. However, 
service will be provided only for the current update level. 


The way each customer obtains access to program service 
depends on the marketing channel through which the program 
was obtained. 


In the United States and Puerto Rico, if the IBM APPC/PC 
program product was obtained through an authorized IBM 
Personal Computer dealer, requests for program service should be 
made through the dealer. If the program was obtained through 
the IBM National Accounts Division or the IBM National 
Marketing Division, requests for program service should be made 
through the service coordinator for the customer. 


The IBM Support Center will help the service coordinator 
diagnose and solve problems. The service coordinator may call 
the IBM Support Center at any time, and will usually be called 
back within eight business hours. The IBM Support Center will 
contact the service coordinator Monday through Friday between 
8 a.m. and 5 p.m., local customer time. 


IBM does not guarantee service results, or that the program will 
be error-free, or that all program defects will be corrected. 


When a report of a defect in an unaltered portion of a supported 

release of the program is submitted, IBM will respond by issuing 

one of the following: 

e Defect correction information, such as corrected 
documentation, corrected code, or notice of availability of 
corrected code 


e A restriction notice 


e A bypass. 
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Corrected code is provided on a cumulative basis on diskettes; no 
source code is provided. Only one copy of the corrections with 
supporting documentation will be issued to the customer 
coordinator or authorized dealer. IBM will authorize various 
agents, such as IBM Personal Computer dealers and service 
coordinators of IBM National Accounts Division and IBM 
National Marketing Division customers, to make and distribute a 
copy of the corrections, if needed, to each IBM APPC/PC user 
that they serve. 


The total number of copies of an update distributed to IBM 
APPC/PC users within a customer’s location may not exceed the 
number of copies of the IBM APPC/PC program products that the 
customer has acquired. 


IBM does not plan to release updates of IBM APPC/PC ona 
routine basis for preventive service purposes. However, should 
IBM determine that there is a general need for a preventive 
service update, it will be made available to all users through the 
same process used to distribute general IBM APPC/PC updates. 


Following the discontinuance of all program services, this 
program will be distributed on an “as is” basis, without warranty 
of any kind either express or implied. 


Glossary 


abnormal termination. A system or program failure, or 
operator action that causes a program (APPC/PC, 
application subsystem or transaction program) to end 
unsuccessfully. See normal termination. 


adapter. An IBM communications adapter interface card 
for the IBM Personal Computer. 


Advanced Program-to-Program Communication 
(APPC). A set of protocols that provide communication 
capabilities between computer programs on diverse 
systems. 


Advanced Program-to-Program Communication for 
the IBM Personal Computer (APPC/PC). A DOS 
extension that performs APPC functions for transaction 
programs running on an IBM PC. 


alert. The primary network management message that 
communicates problem determination information to the 
network operator. 


American National Standard Code for Information 
Interchange (ASCII). The standard interchange 
between data processing systems, data communications 
systems, and associated equipment. The code uses a coded 
character set consisting of 7-bit coded characters (8 bits 
including parity check). The set consists of control 
characters and graphic characters. 


API. Application Program Interface. 
APPC. Advanced Program-to-Program Communication. 


APPC/PC. Advanced Program-to-Program 
Communication for the IBM Personal Computer. 
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application program. A program that processes 
transactions for a specific purpose. Also called a 
transaction program. 


Application Program Interface (API). The set of 
commands, described in this manual, that the application 


subsystem and transaction programs use to communicate 
with APPC/PC. 


application subsystem. A user-supplied set of programs | 
that provide services to APPC/PC and transaction 
programs. 


ASCII. American National Standard Code for 
Information Exchange. 


basic conversation. A conversation between two 
transaction programs using the APPC/PC basic 
conversation API. in typical situations, service 
transaction programs use basic conversations and 
end-user transaction programs use mapped conversations. 
however, either type of program may use either type of 
conversation. 


basic conversation verb. A verb that a transaction 
program issues when using the APPC/PC basic 
conversation API. 


bind. The RU involved in activating an LU6.2 session. 


bind session (BIND). In APPC, the process that APPC 
performs to establish a session between two LUs. 


boundary function. Services provided to a peripheral 
node in an SNA network, by an intermediate or host node. 
These services include message re-formatting and address 
translation. 


byte reversal. The IBM Personal Computer stores all 
numeric 16- or 32-bit values with the low-order (least 
significant) byte stored in the lower-numbered address. 
This format is the reverse of that used in larger IBM 
computer systems. 


X-2 


change-direction protocol. A data flow control 
protocol in which the sending logical unit stops sending 
requests, signals this fact to the receiving LU, and 
prepares to receive requests. 


CICS/VS. Customer Information Control System for 
Virtual Storage. 


class of service. A designation of the path control 
network characteristics, such as path security, 
transmission priority, and bandwidth, that applies to a 
particular session. The end-user program specifies the 
class of service when requesting a session by using a 
symbolic name that APPC maps into a list of virtual 
routes, any one of which can provide the requested level 
of service for the session. 


communication adapter. Hardware that enables a 
processor to perform data communication. 


configuration services (CS). One of the types of 
network services in a control point (SSCP or PNCP) and 
in the physical unit (PU). Configuration services 
activate, deactivate, and maintain the status of physical 
units, links, and link stations. 


confirmation. A program’s acknowledgment that the 
data has been received. 


contention loser. The LU that must request and receive 
permission from the session partner LU to allocate a 
session. 


contention-loser polarity. The designation that an LU 
is the contention loser for a session. 


contention winner. The LU that can allocate a session 
without requesting permission from the session partner 


LU 


contention-winner polarity. The designation that an 
LU is the contention winner for a session. 
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control point. Refers to a system services control point 


(SSCP). 


control verb. One of the verbs a program issues to set 
up the IBM PC hardware and APPC/PC software to 
perform transactions with a remote program. Typically, 
an application subsystem issues these verbs and a 
transaction program issues conversation verbs. 


conversation. The communication between two 
transaction programs communicating over a Type 6.2 
LU-LU session. 


conversational transaction. Two or more programs 
communicating with each other using the services of LUs. 
Among the components in a conversational transaction 
are the transaction programs and the transaction 
resources associated with the programs (including the 
conversations connecting the transaction programs). 


conversation type. A conversation can be either a basic 
conversation or a mapped conversation. 


conversation verb. One of the verbs a transaction 
program issues to perform transactions with a remote 
program. Typically, a transaction program issues these 
verbs and an application subsystem issues control verbs. 


CS. Configuration services. 


Customer Information Control System for Virtual 
Storage (CICS/VS). A host (System/370) program 
product that can be used in a communications network. 


data link. See link. 


data link control (DLC) layer. The SNA layer that 
consists of the link stations that schedule data transfer 
over a link between two nodes and perform error control 
for the link. Examples of data link control are SDLC for 
serial-by-bit link connection and data link control for the 
IBM Token-Ring Network. 


deadlock. A situation that occurs when two or more 
nodes are waiting for messages from each other and 
cannot continue processing verbs. 


dependent LU. An LU with an active session to an LU 
within an SNA host system. A dependent LU cannot send 
BINDs. 


distributed transaction processing services. The set 
of services that enable transaction programs to 
communicate with each other and access remote 
resources, and to aid in synchronization and error 
recovery. 


DLC. Data link control. 


EBCDIC. Extended Binary-Coded Decimal Interchange 
Code. 


error log exit. A routine that APPC/PC can call to log 
errors during a conversation. 


Extended Binary-Coded Decimal Interchange Code 
(EBCDIC). A coded character set consisting of 256 
eight-bit characters. 


flow control. The process of managing the rate at which 
data traffic passes between components of the network. 
Flow control optimizes the rate of flow of message units to 
minimize congestion in the network; that is, to neither 
overflow the buffers at the receiver or at intermediate 
routing nodes, nor leave the receiver waiting for more 
message units. See also pacing. 


FMH. Function management header. 

function management header (FMH). An optional 
field at the beginning of a request unit that carries 
certain logical unit control information. Different types of 
logical units use different types of FM headers: 


Type 6.2 logical units use three types of headers: 


X-5 


e An Attach FM header (FMH 5) to specify the name of 
required characteristics of a partner transaction 
program 


e An Error-description FM header (FMH 7) to describe a 
transaction program error or an ATTACH failure 


e A security FM header (FMH 12) to carry LU-LU 
session password verification data. 


GDS. The General Data Stream data format. (See SNA 
Reference Summary for more information.) 


half-session. A component that provides data flow 
control and transmission control for one of the sessions of 
a network addressable unit. See also session, primary 
half-session and secondary half-session. 


hang. See deadlock. 


hexadecimal. Pertaining to a numbering system with a 
base of 16. Valid numbers are the digits 0 through 9 and 
the characters A through F, where A represents 10 and F 
represents 15. 


host node. A subarea node that contains a system 
services control point (SSCP); for example, a system/370 
computer with OS/VS2 and VTAM. 


independent LU. An LU that does not have an active 
session to an LU within an SNA host system. An 
independent LU can send BINDs. 


intermediate node. A node that provides intermediate 
routing services in an SNA network. 


layer. A grouping of related functions that are logically 
separate from the functions in other layers; the 
implementation of the functions in one layer can be 
changed without affecting function in other layers. 


link. The line connection and the link stations joining 
network or peer nodes. 
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link connection. The physical equipment providing 
two-way communication between one link station and 
other link stations. 


link station. The hardware and software that enables a 
node to attach to and provide control for a link. See also 
primary link station and secondary link station. 


local transaction program. The transaction program at 
the local LU. 


logical unit. A set of logical services by which one user 
communicates with another, using sessions. 


Logical unit Type 6.2. The architectural base for APPC. 
An LU Type 6.2 supports sessions between two 
applications in a distributed data processing environment. 


LU. Logical unit. 
LU 6.2. Logical unit 6.2. 


mapped conversation. A conversation between two 
transaction programs using the APPC/PC mapped 
conversation API. In typical situations, end-user 
transaction programs use mapped conversations and 
service transaction programs use basic conversations. 
However, either type of program may use either type of 
conversation. 


mapped conversation verb. A verb that a transaction 
program issues when using the APPC/PC mapped 
conversation API. 


mode. The set of parameters defining the network 
properties of a session. 


modem. A mechanism that modulates and demodulates 
signals transmitted over data communications facilities. 


mode name. A name that a program uses to request a 
specific set of network properties of a session the program 
wants to use for a conversation. These properties include, 
for example, the highest synchronization level for 
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conversations on the sessions, the class of service for the 
sessions, and the session routing and delay 
characteristics. The network administrator establishes 
the mode names for a network. 


multipoint line. A communication line or circuit 
interconnecting several nodes. Contrast with 
point-to-point line. 


NAU. Network addressable unit. 


negotiable BIND. An RU that can enable two LU-LU 
half-sessions to negotiate the parameters of a session 
when the LUs are activating a session. 


network addressable unit (NAV). A logical unit, 
physical unit, or system services control point. An NAU 
is the origin or the destination of information transmitted 
through the path control network. See also network name. 


network management services function. A set of 
programs to manage a network. The programs receive 
network management data through NMVTs. 


network management verb. The 
TRANSFER MS_ DATA verb is used to provide network 
management information to a network management 
services function within an SNA network. 


network name. The symbolic identifier by which the 
network refers to a network addressable unit (NAV), a 
link station, or a link. 


NMVT. A Network Management Vector Transport RU 
provides alert, problem determination statistics, and other 
network management data to a network management 
services function. 


node. An endpoint of a link or a junction common to 
two or more links in a network. Nodes can be host 
processors, communication controllers, or terminals. 
Nodes can vary in routing and other functional 
capabilities. . 
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nonswitched line. A connection between systems or 
devices that does not have to be made by dialing. Contrast 
with switched line. 


normal termination. Termination that results in 
successful execution of a program. Normal termination of 
APPC/PC is through successful execution of the 
APPCUNLD command. See abnormal termination. 


NS header. The part of a network services RU that 
identifies the type of RU. 


pacing. The technique of limiting the amount of data 
that a program can send or receive at one time to prevent 
overrunning the LU buffers. See also flow control, receive 
pacing, and send pacing. 


pacing window size. The number of RUs that a program 
can send before getting permission to send more. 


parallel sessions. Two or more concurrently active 
sessions between the same two logical units (LUs). Each 
session can have different session parameters. 


partner transaction programs. Transaction programs 
corresponding on the same conversation. 


path control network. The routing portion of an SNA 
network. 


PD Stats. The problem determination statistics that 
enable the SNA network management services function to 
determine and diagnose problems associated with the 
communication links used for sessions. 


peer-to-peer. Communication between two LUs that is 
not managed by a host. 


peripheral node. A node that has no intermediate 
routing function, and is dependent upon an intermediate 
or host node to provide certain network services for its 
dependent LUs. APPC/PC provides a peripheral node 
capability. 
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physical unit (PU). The component that manages and 
monitors the resources of a node, as requested by an SSCP 
using an SSCP-PU session. Each node of an SNA network 
contains a physical unit. 


physical unit (PU) services. The components within a 
physical unit (PU) that provide configuration services and 
maintenance services for SSCP-PU sessions. 


PIP. Program initialization parameter. 
PLU. Primary logical unit. 


point-to-point line. A communication line or circuit 
that connects a single remote node to another node; it can 
be either switched or non-switched. Contrast with 
multipoint line. 


polarity. See contention-winner polarity and 
contention-loser polarity. 


posting. When a transaction program directs APPC/PC 
to post a conversation, APPC/PC enables the transaction 
program to check whether a specific amount of data is 
available in the local LU’s receive buffer. 


primary logical unit (PLU). The logical unit (LU) that 
contains the primary half-session for a particular LU-LU 
session. See also secondary logical unit. 


primary half-session. The half-session on the node that 
sends the session activation request. See also primary 
logical unit and secondary half-session. 


primary link station. The link station that is 
responsible for the control of the link. A link has only 
one primary link station. All traffic over the link is 
between the primary link station and a secondary link 
station. See also secondary link station. 


PU. Physical unit. 


receive pacing. The pacing of message units that a 
component is receiving. See also send pacing. 
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remote transaction program. The partner transaction 
program using the remote LU. 


request/response header (RH). Control information, 
preceding a request/response unit (RU), that specifes the 
type of RU (request unit or response unit) and contains 
control information associated with that RU. 


request/response unit (RU). A generic term for a 
request unit or a response unit. 


request unit. A message unit that contains control 
information such as a request code, function management 
headers (FMHs), end-user data, or a combination of these 
types of information. 


response unit. An LU’s response to one or more request 
units, indicating successful receipt of data or an error 
condition. 


responsible LU. The LU responsible for deactivating a 
session when it is no longer being used by two LUs fora 
conversation. 


return code. A code APPC/PC returns to the issuer of a 
verb to indicate the results of verb execution. 


RH. Request/response header. 

RU. Request/response unit. 

SDLC. See synchronous data link control. 

secondary half-session. The half-session on the node 
that receives the session-activation request. See also 
secondary logical unit and primary half-session. 
secondary link station. Any link station that is not the 
primary link station. A secondary link station can 
exchange data with the primary link station, but not with 


other secondary link stations. See also primary link 
station. 
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secondary logical unit (SLU). The logical unit (LU) 
that contains the secondary half-session for a particular 
LU-LU session. A logical unit may contain secondary and 
primary half-sessions for different active LU-LU sessions. 
See also primary logical unit. 


send pacing. Pacing of message units that a component 
is sending. See also receive pacing. 


sense code. The code that indicates the type of error 
that has occured. Sense codes are logged or sent to the 
partner node in function management headers or negative 
responses. 


session. Communication between LUs. A logical 
connection between two network addressable units 
(NAUs). The connection can be activated, tailored to 
provide various protocols, and deactivated, as requested. 
See also half-session, primary half-session, and secondary 
half-session. 


session activation. The process of exchanging a session 
activation request and a positive response between 
network addressable units (NAUs). See also session 
deactivation. 


session deactivation. The process of exchanging a 
session deactivation request and response between 
network addressable units (NAUs). See also session 
activation. 


session parameters. The parameters that specify or 
constrain the protocols (such as bracket protocol and 
pacing) for a session between two network addressable 


units (NAUs). 


session partner. One of the two network addressable 
units (NAUs) participating in an active session. 


single session. A session that is the only session 
connecting two LUs. 


SLU. Secondary logical unit. 


SNA. Systems network architecture. 


SNASVCMG. The APPC/PC-defined mode, used only for 
CNOS negotiations. 


SSCP. System services control point. 


SSCP-LU session. A session between a system services 
control point (SSCP) and a logical unit (LU); the session 
enables the LU to request the SSCP to help initiate 
LU-LU sessions. 


SSCP-PU session. A session between a system services 
control point (SSCP) and a physical unit (PU); SSCP-PU 
sessions enable SSCPs to send requests to and receive 
status information from individual nodes to control the 
network configuration. 


state. The state of a conversation determines which 
verbs APPC/PC allows a program to issue. For example, 
in receive state the program can only receive data. The 
four states are reset, send, receive, and confirm. 


switched line. A connection between two nodes that is 
established by dialing. Contrast with nonswitched line. 


synchronization level. The specification indicating 
whether the corresponding transaction programs exchange 
confirmation requests and replies. 


synchronous data link control (SDLC). A discipline 
for managing synchronous, code-transparent, serial-by-bit 
information transfer over a link connection. 
Transmission exchanges can be half-duplex over switched 
links, and full-duplex or half-duplex over non-switched 
links. The configuration of the link connection can be 
point-to-point, multipoint, or loop. SDLC conforms to 
subsets of the Advanced Data Communication Control 
Procedures (ADCCP) of the American National Standards 
Institute and High-Level Data Link Control (HDLC) of the 
International Standards Organization. 


systems network architecture (SNA). The description 
of the logical structure, formats, protocols, and 
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operational sequences for transmitting information units 
through, and controlling the configuration and operation 
of, networks. 


systems network architecture (SNA) network. The 
part of a user-application network that conforms to the 
formats and protocols of systems network architecture. It 
provides a reliable method of transferring data among 
programs and provides protocols for controlling the 
resources of various network addressable units (NAUs), 
boundary-function components, and the path control 
network. 


Systems network architecture node. A node that 
supports SNA protocols. See also node. 


systems services control point (SSCP). A control 
point in a host node. It provides network services for 
dependent nodes. 


time-out condition. An error condition indicating that 
a specified amount of waiting time has elapsed without 
the occurrence of an expected event. 


transaction. A unit of communication processing that 
accomplishes a particular result. 


transaction program. An application program that 
performs transactions with one or more remote programs. 


transaction service mode. See mode. 


UNBIND. The RU involved in deactivating an LU Type 
6.2 session. 


verb. Usually, a request by a user program for an 
APPC/PC action. In a few cases, a request by APPC/PC 
for an application subsystem action. A verb requesting an 
APPC/PC action is performed by issuing a software 
interrupt accompanied by APPC/PC-specific information 
stored in registers and memory. 


Virtual Telecommunications Access Method 
(VTAM). A set of programs that control communications 
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between nodes and application programs running on a 
host (System/370) system. 


VTAM. Virtual Telecommunications Access Method. 
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